Control Statements

The following control statements are available in the Highway program.

ABORT - Quit current program
ARRAY - Set user arrays
BREAK - Break out of current process
COMP - Compute variables from expressions
CONTINUE - Go to end of current loop
EXIT - Terminate current phase
FILEI - Input files
FILEO - Output files
FILET - Set path for temporary files
FILLMW - Fill work matrices
FUNCTION - Define Volume, TimeAdjustment, and Cost functions
GOTO - Jump immediately to :label statement
IF … ELSEIF … ELSE … ENDIF - Define IF ENDIF block
JLOOP … ENDJLOOP - Define a loop for destination zones (J)
LINKLOOP … ENDLINKLOOP - Control a link loop for processing link records in the ILOOP phase
LOOKUP - Define lookup tables (see General Syntax)
LOOP … ENDLOOP - Define a user controlled loop
PARAMETERS - Set static parameters
PATHLOAD - Build path, load path, compute selected link matrices
PRINT - Print variable values
PRINTROW - Print a row of a matrix
PROCESS … ENDPROCESS - Set process (phase) blocks
REPORT - Set standard reports
SET - Set multiple variables/arrays to same value
SETGROUP - Set link group codes
SORT - Sort user arrays
SPDCAP - Set Speed and Capacity table values
TURNS - Designate intersections where turn volumes are to be accumulated

ABORT

Aborts the entire run.

Keywords include:

Use ABORT to terminate the program and return a fatal code to CUBE Voyager. It normally is not used, but allows for termination due to some conditions that can be detected in the process. For example: if it is discovered that an LOS matrix is empty when it should have data, the run should be aborted.

MSG - |S| - Optional message that can be printed when the program terminates. For readability, Bentley recommends 100 characters or less.

Example

IF (MW[1][I] != 0) ABORT ;Intrazonal present in MW[1]

ARRAY

Declares user single-dimension arrays.

Keywords include:

VAR=size

Use ARRAY to allocate user arrays that are to be used in the process. An array is different than a variable in that it represents vectored data. Values stored to arrays must be numeric. String values cannot currently be stored in an array. When an array is referenced, it should include an index [], and if the index exceeds the size, the program may fatally terminate. Arrays can be useful for different processes. ARRAY statements are not dynamic (stack oriented); they are allocated prior to any stack operations. When an array variable appears in a SET statement, all the cells in the array are set to the same value.

VAR - |I| - Name of the variable that is to be allocated according to the specified size. VAR must be a unique name. The size following the keyword is the highest index possible for VAR. Size may be either a numeric constant, or a special name. Special names are: ZONES, NODES, LINKS (or NUMLINKS).

Example

ARRAY sum_toll=20
sum_toll[NI.CLASS] = sum_toll[NI.CLASS] + VOLTOT
ARRAY VMT=LINKS

BREAK

Breaks out of a loop.

Upon encountering BREAK, the script immediately passes control to the statement after the associated loop.

If BREAK is within a LOOP … ENDLOOP or JLOOP … ENDJLOOP block, control passes to the statement following the associated ENDLOOP (loop variable remains intact) or ENDJLOOP (J is reset to 1).

If BREAK is not within a LOOP or JLOOP block, the script terminates processing for the I zone but does not bypass output and zonal reporting statistics.

Example

LOOP L1=1,3
   IF (condition)
      statements
   ELSE
      BREAK          ; jump to IF statement
   ENDIF
ENDLOOP
IF (condition) BREAK ; no more processing for this origin zone

COMP

Computes a variable, matrix, or matrix element from an expression.

Keywords and sub-keywords include:

MW
- EXCLUDE
- INCLUDE
VAR

Usage:

VAR=expressionMW[n]=expression,INCLUDE=listofJzones,EXCLUDE=listofJzones

Use the COMP statement to compute variable and work matrix values.

MW - |KN| - Value for a working matrix. You can specify this keyword in two formats:
- MW[n] — Defines the index n of a working matrix. Matrices can contain up to MAXMW sub-matrices, as indexed by n. The index n may be either a constant or a variable name.
  
  The program solves the expression for all values of J (1 through Zones), filtering values indicated by any INCLUDE or EXCLUDE lists on this statement.
  
  Within a JLOOP statement, the program only solves the expression one time only, with J being the value of the loop’s current J.
- MW[n][c] — Defines the value for column c in working matrix n. The second index, c, must be between one and Zones. The program solves the expression one time only, with J being the loop’s J if within a JLOOP, or 1, if not.
MW - EXCLUDE - |IP| - Optional. Values of J excluded when computing the MW[n] expression. As the program internally loops on J, the program compares J to the values in the EXCLUDE list. If the current J is on the list, the program does not evaluate or store the expression for that J.

Specified values can range from 1 to the highest zone number.

Filter applies to all MW[n] values on the COMP statement.

Not permitted if COMP statement within JLOOP … ENDJLOOP block.

Always processed after INCLUDE subkeyword. By default no zones are excluded.
MW - INCLUDE - |IP| - Optional. Optional. Values of J included when computing the MW[n] expression. As the program internally loops on J, the program compares J to the values in the INCLUDE list. If the current J is not on the list, the program does not evaluate or store the expression for that J.

Specified values can range from 1 to the highest zone number.

Filter applies to all MW[n] values on the COMP statement.

Not permitted if COMP statement within JLOOP … ENDJLOOP block.
VAR - |KN| - Name of a variable where the result of expression is to be stored. The name may be as long as desired (within reason). The expression is solved one time for each encounter, with J being either one (not in JLOOP), or the value of the JLOOP J. If expression results in a character string, the variable must be a character string variable. All variables are assumed to be numeric variables, unless their first appearance as a result in a COMP statement is with an expression that results in a character string. Examples:

abc = ‘123’

def = 123

abc = def ; invalid: abc has been declared a string

abc = abc + ‘456’ ; valid

abc = abc + def ; messy – don’t mix

jkl = 1 ; jkl is declared numeric

jkl = xyz ; invalid: xyz is declared a string (later)

xyz = ‘xyz’ ; xyz is declared a string

If a COMP statement includes any INCLUDE or EXCLUDE filters, the filters apply to all MW[]= values, and special matrix functions on the statement, no matter where they appear on the statement. EXCLUDE is processed after INCLUDE. INCLUDE and EXCLUDE may not be specified within a JLOOP.

Special matrix variables

MW[] MI.n.name MI.n.matnum

The expression is a standard CUBE Voyager numeric expression, but there are some special variables that may be used within it:

Matrix variables

MW[Rexpression] - Value from any work matrix; the column index (not explicitly expressed) will be supplied as J. Rexpression may contain nested MW[]; be careful! MW[Rexpression][Cexpression] is the value from any work matrix for zone Cexpression.
MI.n.name - Value from the MATI[n].name matrix; the column index (not explicitly expressed) will be supplied as J. The row index [n], must be a constant. MI.n.name[Cexpression] is a variation; the column index is computed.

Valid matrix names contain only alphanumeric characters, spaces, and underscores (_). If matrix names have spaces, then you must include the entire MI matrix reference in double quotes to recognize the name. For example:
```
MW[1]="MI.1HBW TRIPS"
```
MI.n.matnum - Value from the MI[n].matnum matrix; the column index (not explicitly expressed) will be supplied as J. The row index [n] and the matnum must be constants. MI.n.matnum[Cexpression] is a variation; the column index is computed.
ZI.n.name - Value from the ZDATI[n].name matrix; the zone index (not explicitly expressed) will be supplied as I. ZI.n.name[Cexpression] is a variation; the zone index is computed.

Special matrix functions

ROWSUM ROWCNT ROWMIN ROWMAX ROWAVE ROWFIX ROWFAC LOWEST LOWCNT ROWADD ROWMPY ROWDIV

In addition to the standard numeric expression functions (abs, exp, int, ln, log, max, min, round, sqrt — see General Syntax for more details), some special purpose functions are available. The matrix-oriented functions process all cells in a matrix (subject to the restrictions of any INCLUDE and EXCLUDE lists), and should not be used within JLOOP blocks and MW[]= expressions. Normally, they should be used only as VAR = ROWFUNC(#).

Most of these functions could be duplicated with a combination of MW[]= statements. The function format has two advantages: coding is much easier, and processing is more efficient. Combining functions on a single statement is permissible; they will be processed in appropriate order. Example: DUMMY = ROWFAC(3,1.5) + ROWFIX(3) will factor matrix 3 and then convert it to integer.

In the following matrix function descriptions, the first argument (mw) indicates the work matrix to process, and must be specified. If "lo,hi" is allowed, and lo is supplied, and hi is not, hi will be set to lo. Lo and hi are inclusive values. If an invalid argument is detected by a function, the function will return a zero, without any diagnostics.

MATRIX functions

LOWCNT - The actual number of cells that was used in the summary is stored in the variable LOWCNT. Warning: Dividing by LOWCNT if it is 0, will cause a program error message (too many will be fatal).
LOWEST(mw,n) - Sum of lowest n cells.
LOWEST(mw,n,lo,hi)- Sum of lowest n cells, including only cells with values greater than or equal to lo, and less than or equal to hi.
LOWEST(mw,n,lo,hi,z,z,…) - Sum of lowest n cells, including only cells with values greater than or equal to lo, and less than or equal to hi, and exclude the values for J=z,z,…

LOWEST is quite useful for computing an intrazonal value based upon the proximity to the nearest zones. The range of arguments is to provide for most types of situations. With lo and hi, it is possible to exclude possible dummy zones that may appear as zero in the row. With z, specific zones can be excluded; normally, the intrazonal cell (I) would be excluded. This exclusion is in addition to any that may be on an EXCLUDE list.

ROWADD(d,s1…sn) - Add matrices MW[s1], MW[s2], … MW[sn] to matrix MW[d].

Same as:
```
MW[d]=MW[s1] + MW[s2] + MW[sn]
```
ROWAVE(mw) - Average cell value, including only cells with values not equal to 0.
ROWAVE(mw,lo,hi) - Average cell value, but include only cells with values greater than or equal to lo, and less than or equal to hi.
ROWCNT(mw) - Number of cells with values not equal to 0
ROWCNT(mw,lo,hi) - Number of cells with values greater than or equal to lo, and less than or equal to hi; can include 0.
ROWDIV(d,s) - Divide MW[d] by MW[s] making all divided-by-zero cells equal to 0.

Same as:
```
JLOOP
  IF (MW[s] == 0)
     MW[d] = 0
  ELSE
     MW[d] = MW[d] / MW[s]
  ENDIF
ENDJLOOP
```
ROWFAC(mw,fac) - Factors the row by fac.

Same as MW[mw] = MW[mw] * fac
ROWFIX(mw) - Convert mw to integer values (start at column intrazonal + 1, with rounding factor = 0).
ROWFIX(mw,n) - Convert mw to integer values (start at column n, with rounding factor = 0).
ROWFIX(mw,n,rnd) - Convert mw to integer values (start at column n, using specified rounding factor).

ROWFIX converts the values in each cell of the matrix to integers (that is, drops all fractional portions of the number) in such a manner to ensure the integer total is consistent with the original total. It converts each cell to an integer value after adding the rounding factor and the accumulated fractional portions from the previously treated cells. With a rounding factor of 0 each cell is truncated and its fractional remainder is carried to the next cell. With a rounding factor of 0.5, each cell is rounded to the nearest integer and the difference (original – rounded) is carried to the next cell.

If the process always began at zone 1, the lowest numbered zones would never get their fair share of the fractions. To eliminate this bias, the default condition is to start at the cell after the intrazonal cell and wrap around until the intrazonal cell is the last cell processed. The optional second argument specifies which cell the process is to end with.
ROWMAX(mw) - Maximum value in the row.
ROWMIN(mw) - Minimum value in the row.
ROWMPY(d,s) - Multiply MW[d] by MW[s]

Same as:
```
MW[d]=MW[d]*MW[s]
```
ROWSUM(mw) - Row total.
ROWSUM(mw,lo,hi) - Row total, but include only cells with values greater than or equal to lo, and less than or equal to hi.

Example 1

MW[mw][I]=LOWEST(mw,4,0.01,5,I)/max(1,LOWCNT)/2

Example 2

MW[2]=J
MW[K]=MW[2] * MW[5]) / SQRT(A*MW[3][MW[22]])
A=1, B=2, MW[A]=A+B INCLUDE=1-5,8,47-93
MW[3]=5*A, MW[4]=MW[3]*2, MW[K][I%10+1]=ODD,
   INCLUDE=1-100,401-500, EXCLUDE=90,93,452
   ; applies to the MW[]s=
ABC=LOOKUP(DEF)*3
/* move input matrices to work areas */
MW[11]=MI.1.1, MW[12]=MI.1.2, MW[13]=MI.1.3
MW[21]=MI.2.1, MW[22]=MI.2.2, MW[23]=MI.1.3

CONTINUE

Jumps to the end of a loop, bypassing all intermediate statements.

If CONTINUE is within a LOOP … ENDLOOP or JLOOP … ENDJLOOP block, control passes to the appropriate ENDLOOP or ENDJLOOP statement. Otherwise, processing for the I zone is terminated, but output statistics will not be bypassed.

Example

LOOP L1=1,3
   IF (!(condition)) CONTINUE
ENDLOOP
IF (condition) CONTINUE
   ; no more processing for this origin zone
LOOP L2=K1,K2,KINC
   LOOP L3=L2,L2+5
      IF (condition) CONTINUE ; jump to ENDLOOP for L3
   ENDLOOP
ENDLOOP

EXIT

Terminates stack processing. When the program encounters an EXIT statement, the program goes to the end of I-loop processing.

Example

IF(expression)EXIT

FILEI

Note: See FILEI for general information about FILEI and for important limitations when using Application Editor.

FILEI, its keywords and subkeywords define the input HIGHWAY’s input data files.

Keywords and sub-keywords include:

JUNCTIONI
- N
- PERIOD
- SET
LOOKUPI
MATI
NETI
SUBAREANETI
TOLLMATI
- ENTRYGATE
- EXITGATE
- NETIENTRY
- NETIEXIT
- NETITOLLROAD
- TOLLFACTOR
- TOLLROUND
- TOLLS
TURNPENI
- LIST
- MISSINGLINK
ZDATI
- AVE
- AVEX0
- CNT
- DEFAULT
- FIRST
- LAST
- MAX
- MIN
- NAME
- SELECT
- SUM
- Z

Matrix data is read dynamically (at the start of each I-loop), and must be in origin zone (I) order, whereas zonal data is read prior to the initiation of the I-loop, and need not be in any specified order. Data from MATI and ZDATI files are accessed via stack statements, and are identified as MI.n.name and ZI.n.name. The n designates subscript of the file, name designates the matrix name or number. CUBE Voyager matrices can have names and/or numbers, other matrices have only numbers, and zonal data files have names only. Example: MI.1.3 indicates matrix number 3 on the MATI[1] file. ZI.6.POP indicates the POP variable from ZDATI[6] file. Valid matrix names contain only alphanumeric characters, spaces, and underscores (_). If matrix names have spaces, then you must include the entire MI matrix reference in double quotes to recognize the name. For example:

MW[1]="MI.1HBW TRIPS"

On the FILEI statement the subscript is either explicitly, or implicitly, specified. MATI=… defaults to MATI[1], and MATI[3]=name3,name4,name5 sets up MATI[3], MATI[4], and MATI[5]. Since it is required that ZDATI files have variables explicitly defined for them, the vector form of ZDATI (ZDATI=file1, file2…) will be treated as an error.

When an input file is used in an expression, it may have an additional subscript appended to it to specify a zone number. For matrices, the subscript references the column within a row, and for zonal data, it references the nth item in the vector. Zonal data can be viewed as having zones rows with one column per zone, or as one row having zones columns (user’s choice, it doesn’t matter). If there is no subscript specified, the current value of J is used. J will always be in the range 1-zones. Example: MI.6.3[I] accesses the intrazonal cell. ZI.1.TRMTIME[I] and ZI.1.TRMTIME[J] reference the origin and destination terminal times, respectively.

TURNPENI designates a file that contains intersection movement functions and penalties. This file may be read and kept in memory for use during any path development processes (specified with PATH on PATHLOAD statements). Even if the file is designated on a FILEI statement, the penalties will not automatically be applied during path development; the user must specify which penalties are to be applied on each PATH selection. The file has two sections: functions and movements.

The function section is optional, but allows the user to specify that a penalty is to be computed from an expression. If a function contains a C variable (movement capacity), the penalty will be revised between iterations in the ADJUST phase.

Each record in the movement section designates a specific movement (a-b-c), a set identifier for the movement, and the penalty to be assessed. For example:

a	b	c	set#	turnpen
11	23	15	1	-1	(Prohibitor)
1	12	13	3	2	(Constant)
15	58	36	8	FUNC1(500)	(Function)

The penalty may be a prohibition, a fixed unit penalty, or a reference to a function in the function section. A prohibition is designated as the constant -1. It is the user’s responsibility to make sure that the penalty values are in the proper scale and units as the paths to which they are being applied.

Turn functions are designated as numeric expressions that may contain constants and the variables: T, C, PrevPen. T is the turn volume at the intersection (it may alternatively be named TURN); C is the capacity of the movement, and PrevPen is the penalty that was used in the previous iteration.

T is vectored (that is, it may contain an index []). T is the total volume for the movement; it is 0 at the first iteration, but is the result of the T=expression on the TURNS statement after the first iteration. If there is no TURNS statement, T will automatically be the sum of all loadings. T[1] would indicate the turning volume associated with any PATHLOAD VOL[1] statements. T[0] and T are the same variable. If a T is specified with an index for which there is no PATHLOAD VOL[index], the value of T[] in the expressions will be 0. Care must be taken if a fixed penalty is to be established for the first iteration, and then dynamic values are to be used after the first iteration. This is usually done by using the MAX function in the expression. For example: Func1=MAX(2.00,T/C*5.00). In this example, since T would be 0 on the first iteration, the initial penalty would be 2, and it would vary after the first iteration. If the 2 unit penalty was to remain in effect for all iterations, and be increased according to the T/C ratio, the expression would be: Func1=2+ T/C *5.

C is obtained from the record in the movement section as an argument of the function. To apply the above Func1 (2+T/C*5), with C=500, the movement record would be coded as: 100 200 201 0 Func1(500). This designates that the movement 100-200-201 is to be penalized 2 units on the first iteration and then the penalty will be increased according to a T/C ratio (with C being 500) after the first iteration. If there were no C affixed to the Func1 on the movement record, the C would be considered as 0 in the computations. (Warning: Be careful not to create divided-by-zero errors when applying functions with C=0.)

TURNPENI function records are structured as: FuncName=expression. The name is what the user desires, and the expression is any valid numeric expression that may contain numbers, standard functions, T, C, PrevPen.

TURNPENI movement records are structured as: A B C Set Penalty (one set per record). The records are white space delimited (space, comma). A is the entry node to the intersection, B is the intersection node, and C is the exit node. Set is a number in the range of 0-8. If the set number is 0, it is applied any time that penalties are in effect, no matter what the designated sets are. There may be up to 9 records (sets 0-8) for the same movement. During path building, when the movement is detected and PENI= is specified in the PATHLOAD statement, the penalty process will automatically apply set 0, if there is a set 0 for the movement. If there is no set 0, the penalty is assumed to be 0. Then it will check all the other possible sets for the movements; it there are additional sets, the penalty for the highest set number that matches the highest PENI designation for the PATH process will be used. NOTE that any movements that have functions specified will cause the B node to be included as a node for which TURNS are to be kept, and will be reported on the TURNVOLO file.

JUNCTIONI designates a file or CUBE Geodatabase network containing descriptions of junction models. The format of the file is discussed in Intersection modeling. N specifies a list of nodes where the intersection modeling is to be invoked during the ADJUST phase. However, invoking intersection modeling for a node where there is no model description has no effect. PERIOD is the model period in minutes. It is used to convert the assigned volumes into units of per hour, and it is one of parameters of the queuing delay equation.

Executing a junction model produces turning delays that may be applied during the next iteration of capacity restraint. This form of output is similar to a set of turn penalties, and the turn penalty set numbering system applies. The SET keyword designate the turn penalty set to contain the model results. Turn penalty records may be applied with higher or lower priority (that is, set number) than the calculated delays.

FILEI keywords

JUNCTIONI - |KF| - Specifies the input junction file or CUBE Geodatabase network. Note if intersection data is loaded from a CUBE Geodatabase network, the JUNCTIONI keyword designates the filename followed by a backslash and the name of the CUBE Geodatabase network.
- JUNCTIONI - N - |IP| - Optional. Specifies the nodes where intersection modeling is to be invoked. A junction that is not invoked has no effect. Invoking intersection modeling where there is no junction described has no effect. Only those nodes that both have a model description and are listed in this list are actually modeled.
- JUNCTIONI - PERIOD - |R| - Duration of the model period in minutes. The input demand matrix should be in units of vehicles (or PCU) per model period.
  
  Note: If PARAMETERSMODELPERIOD is used, this subkeyword will be ignored.
- JUNCTIONI - SET - |I| - Specifies which turn penalty set will contain the delays calculated by the junction models.
- LOOKUPI - |FKV999| - Name of file containing records for a lookup function implemented with the LOOKUP control statement.
  
  Equivalent to the FILE keyword of the LOOKUP control statement. You must index LOOKUPI.
- MATI - |KFV20| - Specifies the input matrix files. The files must be CUBE Voyager, TP+, MINUTP, or Tranplan binary matrices.
- NETI - |KF| - Specifies the input highway network file. It MUST be a CUBE Voyager or TP+ binary network, or a CUBE geodatabase network stored in an MDB or GDB geodatabase. If specifying a CUBE geodatabase network, the NETI keyword designates the filename followed by a backslash and the name of the CUBE geodatabase network. The link variables from the network are referred to as LI.name.
- SUBAREANETI - |KF| - Specifies a file that contains subarea network information. In most cases the network will be one created by the polygon subarea network extraction process in CUBE. If CUBE is used to create the subarea network, the subarea will be set up properly, with the proper node renumbering and cordon link specification. This keyword is used in conjunction with the FILEO SUBAREAMATO = and PATHLOAD SUBAREAMAT[] = expressions. See ILOOP phase for details about subarea processing.
  
  The node records of the network contain both the subarea node number (N) and the number (OLD_NODE) that N was in the network from it was extracted, The records also contain the variable SUB_TYPE that indicates the type of node with relationship to the original network.
  
  The SUB_TYPE values are:
  - 0=insignificant
  - 1=internal (subarea) zone
  - 2=external gateway to the subarea network
  - 3=internal exit from subarea
  If these values are altered from those that Viper or CUBE Base wrote, the results will be unpredictable.
TOLLMATI - |KF10| - Specifies the input toll matrix files. The specified files are toll-point to toll-point records and may be input as DBF, MDB table or delimited text records.

See Path-based tolls.
TOLLMATI - ENTRYGATE - |S| - Field name or field number on the input TOLLMATI file that holds the entry toll gate numbers. If the input file is a DBF or MDB table, the ENTRYGATE value must be a field name from the input table. If the input file is a delimited ASCII file then the ENTRYGATE value is a field number on the input file. If ENTRYGATE is not specified, the first field on the input file will be used. Valid value range for entry toll gate numbers is 1-999.
TOLLMATI - EXITGATE - |S| - Field name or field number on the input TOLLMATI file that holds the exit toll gate numbers. If the input file is a DBF or MDB table, the EXITGATE value must be a field name from the input table. If the input file is a delimited ASCII file then the EXITGATE value is a field number on the input file. If EXITGATE is not specified, the second field on the input file will be used. Valid value range for exit toll gate numbers is 1-999.
TOLLMATI - NETIENTRY - |S| - NETI link attribute that contains the entry gate numbers. The numbers in this link attribute correspond to the numbers in the ENTRYGATE field of the TOLLMATI file. If NETIENTRY is not specified the name will default to TOLLENTRY and it is assumed this link attribute name is available on the input NETI network.
TOLLMATI - NETIEXIT - |S| - NETI link attribute that contains the exit gate numbers. The numbers in this link attribute correspond to the numbers in the EXITGATE field of the TOLLMATI file. If NETIEXIT is not specified the name will default to TOLLEXIT and it is assumed this link attribute name is available on the input NETI network.
TOLLMATI - NETITOLLROAD - |S| - NETI link attribute that contains the toll road indicator. All links with a non-zero value for this attribute are considered part of one closed toll system in the network. The numbers in this link attribute needs to be used to correspond to one unique toll system in the network, and no gates or links can be part of multiple toll systems. If NETITOLLROAD is not specified the name will default to TOLLROAD and it is assumed this link attribute name is available on the input NETI network.
TOLLMATI - TOLLFACTOR - |R10| - Up to 10 toll factors may be specified, one for each toll set. If specified the factor is applied to all toll values in the TOLLMATI file for the set. The TOLLFACTOR provides a method for quickly factoring tolls for sensitivity analysis.
TOLLMATI - TOLLROUND - |R| - Allows for rounding of tolls or factored tolls to the nearest units specified. For example if a toll, coded in the TOLLMATI file for a particular entry to exit movement is US$1.50, and a TOLLFACTOR of 1.2 has been specified to test a 20% toll increase, the factored toll value would be US$1.80. By specifying TOLLROUND=0.25, the applied toll value for this movement would then be US$1.75 (that is,. rounded to the nearest US quarter dollar).
TOLLMATI - TOLLS - |S10| - Field name(s) or field number(s) on the input TOLLMATI file that holds the toll values. Up to 10 toll value sets may be coded. If the input file is a DBF or MDB table, the TOLLS value(s) must be a field name from the input table. If the input file is a delimited ASCII file then the TOLLS value(s) is a field number on the input file. If TOLLS is not specified, the third and subsequent fields on the input file will be used for up to 10 toll sets. Tolls can be coded as true toll values or in any units the user desires.
TURNPENI - |KF| - Specifies the input file that contains the turn penalty functions and movement records.
TURNPENI - LIST - |?| - Switch to designate if the penalty values are to be listed to the print file.
TURNPENI - MISSINGLINK - |I| - Designates the level of severity for any turning movements where links appear in the TURNPENI file, but the A-B and the B-C links are not both in the NETI network. Possible values:
- 0 - Ignore completely (default value)
- 1 - Write warning
- 2 - Generate fatal error
ZDATI - |KFV10| - Specifies the input files containing zonal data. There can be up to 10 zonal data files. Zonal data is data which is specific for each zone. Every zonal record must include a field that identifies the zone to which the record data applies. Aside from the zone number, any fields from the record can be extracted and used by the program.

The file format can be any of: ASCII, DBF, MDB, or a CUBE Voyager or TP+ binary network. The program will try to detect what type of file it is. If it can not identify the file as a DBF, MDB, or a CUBE Voyager or TP+ network, it will assume ASCII. When the program detects a CUBE Voyager or TP+ network file, it opens the node database portion of the file as zonal data.

If the file is of ASCII format, the fields to be extracted must be named and identified on the ZDATI statement by either relative field number, or by exact column positions on the records. The field that contains zone number must be specified using ‘Z=’ keyword.

If the file is a database or a CUBE Voyager or TP+ network, it is not necessary to name the fields to be extracted. All fields will be extracted and can be referenced, in the script, by existing field names from the input file. The specification of zone number field is optional for those two file formats. If ‘Z=’ is present, the specified field will be used to extract zone number. Otherwise, the program will try to determine the zone number field based on file type. For DBF and MDB files, the program will go through all field names to find a match with one of the following possible zone field names, in the given order: {Z, I, J, ZONE, ZONA, TAZ}. The first matched name will be used to extract zone number. (Note: For files with more than one possible zone field from the list above, it is recommended to specify zone number field explicitly to ensure the correct field is used.) For CUBE Voyager or TP+ network files, node numbers (N) will be used as zone numbers by default.
ZDATI - AVE - |SV| - Average of all records. 1
ZDATI - AVEX0 - |SV| - Average of all records, where the value from the file records is not 0. 1
ZDATI - CNT - |SV| - Count of the records that contain the variable. 1
ZDATI - DEFAULT - |R| - Value with which to initialize the array for the named variable. Then, if there are no records for a zone, or the field is blank on a record, this value will be used.
ZDATI - FIRST - |SV| - Directly from the record from the FILEI with the lowest index[]. 1
ZDATI - LAST - |SV| - Directly from the record from the FILEI with the highest index []. 1
ZDATI - MAX - |SV| - Maximum value of all the records. 1
ZDATI - MINIMUM - |SV| - Minimum value of all the records. 1
ZDATI - NAME - |S| - Identifies a data variable that is to be extracted from each record. Only the variables named will be extracted. If the file is a dbf, the value for each name is the name from the dbf dictionary. In most dbf cases, name=name would be the standard, but it is not necessary to keep the same names. For text files, the value assigned to name is either a field number (delimited format), or the columns (fixed format) where the variable is located on the record. All names must be specified with the same format; the first name value (including Z) establishes the format. If the first value is a number, fixed format is assumed; otherwise, delimited format is assumed. If delimited format is specified, each name value MUST end in a number. It doesn’t matter what string precedes the number (the value need not be prefixed with a string). Example: Z=#1,POP=#2, AREA=3, SALES=xxx4. These are all be valid, because Z specified triggered delimited format. Z=1-5,POP=#2 would be invalid because Z specifies fixed format.
ZDATI - SELECT - |S3| - Used to cause selective reading of zonal data records from ASCII files. The program will compare a field from each record with the string specified in SELECT[1], and if the comparison fails, the record is bypassed. This selection is not used if SELECT is not specified. The second SELECT value specifies the field to be compared with. If the value is a number, it designates the beginning column of the comparison field on the input record, and an optional third value can be specified to designate the ending column. The second and third values must both be numeric and should be separated by a dash. If the second field is not numeric, but ends with a number (Example: #1), it is assumed that the value indicates a relative field number on the data record; that field is the comparison string. The third value is ignored if the second value is a free field definition.
ZDATI - SUM - |SV| - Sum of all records. 1
ZDATI - Z - |S| - Identifies where the zone number identifier is found on each data record; Z MUST be specified, even if the file is a dbf. Z is a special case for name= (below).

Footnotes

to use in obtaining the value for the variables that are listed following the keyword. The values for the variables will be obtained only from file records that contain the variable. A variable may appear in only one keyword list; any variables that are not in any list will be set to LAST.

Caveat: The program establishes a buffer to read file records into. It has to know how long a buffer is required. With DBFs and fixed format records, the required length is known, but with delimited format, the required length can not be estimated exactly. For delimited files, the record length is estimated by multiplying the highest field number by 10. If the estimated length is inadequate, a dummy variable with a high field number can be specified to generate a larger record length.

Example

NETI=network.net  ; TPP binary network file
MATI=test11.dat, test12.dat ; MINUTP binary matrix files
MATI[4]=tppltrips.mat ; TPP or MINUTP matrix file
TURNPENI=time.pen, MISSINGLINK=1
ZDATI[1]=housing.txt, Z=#1,DU1=#2,DUPLEX=3,MULTI_FAMILY=4,
CONDO=5,RETIREMENT=6
ZDAT[4]=pop.txt,Z=1-5,poptotal=6-15,popmale=16-25,popfemale=26-35,
popyouth=36-45,pop19-65=46-55,popsr=56-65,
poptotal=sum, popmale=cnt

FILEO

Specifies files that the Highway program outputs.

Keywords and sub-keywords include:

ESTMDATO
- LINKTOICP
- NAME
ESTMICPO
- CONFVAR
- COUNTVAR
- DEFAULTCONF
- FORMAT
- SCREENLINE
- VAR
JUNCTIONO
MATO
- COMBINE
- DEC
- FORMAT
- MO
- NAME
NETO
- APPEND
- DEC
- EXCLUDE
- INCLUDE
PATHO
- COSTDEC
- ITERS
PRINTO
- APPEND
SUBAREAMATO
- DEC
- FORMAT
- NAME
TOLLVOLO
- DEC
- DELIMETER
- FORMAT
- NAMES
- INCLUDE0
- MOMO
- MULTITOLL
- NAMES
- OFFGATES
- ONGATES
- PATHSETS
- TOLLMATI
- TOLLSETS
- VOLSETS
TREEO
- ALTNODEFIELD
- APPEND
- CELLTYPE
- DELIMITER
- FORM
- FORMAT
- LISTALTNODES
- LISTCOLNUMS
- LISTNETNODES
- LISTLINKS
- MAXPERLINE
- ORIGINTYPE
- ROWTYPE
TURNPENO
TURNVOLO
- DEC
- DELIMITER
- FORMAT
- INCLUDE0
- NAMES
- QUEUEDATA
- VARS

Use FILEO to specify the number and types of files that are to be written by the program. Requested matrices are written for every origin zone for every iteration, but are combined into a single combined matrix at the end of the application. A single network with appended volumes and associated variables is written at the end of the application. A turning volume file must be requested if a TURNS statement is used.

There MUST be a NETO specified if assignment is to be made; there would be no use in running the program if there was no way to obtain the results. By default the NETO file will contain all the input variables from NETI plus the variables V, VT, VC, TIME, CSPD (congested speed), VDT (vehicle distance traveled), VHT (vehicle hours traveled) and a Vn, and VnT for every VOL[n] specified on any PATHLOAD statements. VT and VnT are the non-directional (two- way) counterparts of V and Vn. (Non-directional volumes can be turned off using NETO EXCLUDE=T_.) These appended variables will have an assignment number appended to their names. If there were no prior assignment result variables appended to the link records, the assignment number will be 1. Thus, the first assignment variables will be named V_1, VT_1, VC_1, TIME_1, V1_1, V1T_1 etc. If the NETI file contains any variable whose name ends in _#, the NETO appended variables will have an appended number that is one greater than the highest _# from NETI.

The following list summarizes the abovementioned additional output NETO attributes from the assignment:

TIME_ = Congested travel time
CSPD_ = Congested speed
Vn_ = Volume for class n for every VOL[n] specified on any PATHLOAD statement
V_ = Total volume calculated applying the V function
VT_ = Non-directional (two-way) total volume (counterpart of V)
VnT_ = Non-directional (two-way) volume for class n (counterpart of Vn_)
VC_ = V over C (capacity) ratio
VDT_ = Vehicles x Distance travelled
VHT_ = Vehicles x Time travelled

If the NETO file is being written to a CUBE geodatabase network in an MDB file, the source geometry for links in the output network will come from the geometry of the input network. If the input network is a binary network, then the output NETO file will have no associated geometry and will be displayed as straight-line links when opened in the CUBE GIS window.

The FILEO TOLLVOLO [#] file output keyword, along with its sub keywords, provides users with the capability to output gate-to-gate toll trips captured with the TOLLPATHSET keyword in PATHLOAD statement. Three different file formats (text, DBF and matrix) are supported with this keyword. Below is a description of each of the keywords. The keyword descriptions follow the same format as used in CUBE help.

FILEO keywords

ESTMDATO - |FV20| - Specifies the file name(s) for the output screenline data file(s) (*.DAT) required by CUBE Analyst. Up to 17 files are allowed.

It is not necessary to have a ESTMDATO for every ESTMICPO. Only one ESTMDATO file needs to be created if multiple ESTMICPO files are created with the same COUNTVAR setting.
ESTMDATO - LINKTOICP - |I| - Number specifying which ICP file the output is linked to. The default is to link to the ICP file with the same index (e.g. ESTMDATO[12] links to ESTMICPO[12]).
ESTMDATO - NAME - |SV| - Specifies the names for the screenlines in the ESTMDATO file. There need not be a name for each screenline, but it is suggested that they be included to help in documentation of the file. A default name of SL A-B will be supplied by CUBE Voyager if no NAME is provided for a screenline.
ESTMICPO - |FV20| - Specifies the file name(s) for the output intercept file (*.ICP) that is required by CUBE Analyst. Up to 17 files are allowed.
ESTMICPO - CONFVAR - |S20| - Specifies the link array that contains the count confidence values. The value may be an lw.array or li.array.
ESTMICPO - COUNTVAR - |S20| - Alternate to using VAR. Specifies the link array that contains the counts. Links that have values in this array will be trapped for inclusion in the matrix estimation. The value may be an lw.array or an li.array. If using COUNTVAR, then do not specify VAR.
ESTMICPO - DEFAULTCONF - |I| - Default confidence value applied if CONFVAR is not set or contains an illegal value (<=0). Valid range is 1 to 10,000.
ESTMICPO - FORMAT - |I| - Toggles the format of the output ICP file(s).
- 0 - legacy format; will only work with original Analyst.
- 1 - optimized format (50-80% smaller file size); will only work with Analyst Drive.
Default is 0.
ESTMICPO - SCREENLINE - |S20| - Specifies the link array that contains screenline numbers for the links. If there is no value in the array for a link that has a count, the program will assign a screenline number to it automatically. If SCREENLINE is not specified, the program will assign a unique screenline number to each link with a value in the VAR array. If a link has a value in the SCREENLINE array, but does not have a value in the VAR array, the link is ignored in the matrix estimation. The value may be an lw.array or an li.array.
ESTMICPO - VAR - |S20| - Replaced by COUNTVAR. Specifies the link array that contains the counts. Links that have values in this array will be trapped for inclusion in the matrix estimation. The value may be an lw.array or an li.array.

If using V**AR**, do not use COUNTVAR. However, Bentley recommends replacing all instances of VAR with COUNTVAR.
JUNCTIONO - |F| - Specifies the file name where the results of junction modeling may be stored for display.
MATO - |FV20| - Specifies the filename for the MATO specified.
MATO - COMBINE - |?| - This keyword, when set to True, is used to combine the matrix assignments estimated in each iteration of the highway assignment. The all-or-nothing assignments are weighted (averaged) in a manner consistent with the volume combination method defined by PARAMETERSCOMBINE.

The averaging is performed every n iterations, where n is specified by PARAMETERSMATOADJUST.

The most common application of this feature would be with SELECTLINK analysis, where it is required. The MATRIX program does not have an equivalent function.

Default value is True.
MATO - DEC - |SV*| - Specifies the format for the MOs. There is a separate DEC for each MO. The value can be a number or the character D or S.
- A number value (0-9) indicates the output matrix cells are to be integerized with that many decimal places preserved. Only the first digit of DEC is read; ie DEC=14 is read as 1.
- The letter S indicates that the cells are to be stored with three decimal places, while D indicates four decimal places.
All internal work matrices are maintained in double precision floating point format (eight bytes per cell), but can be written to MATO files in different formats in order to keep the storage requirements to a minimum. The reader is urged to read the description of FILEO MATO DEC in Matrix Program for a more detailed explanation of the possible binary options. If no DEC value is defined for a matrix, the default value will be integer with 2 implied decimal places. DEC is not applicable when FORMAT=MINUTP is specified.
MATO - FORMAT - |S| - Specifies the format of the MATO:

TPP - Standard CUBE Voyager or TP+ matrices (default)

MINUTP - Standard MINUTP matrices
MATO - MO - |IVP| - Specifies the MWs that are to be included in the MATO. MW may be indexed, but care should be taken to not leave holes in the final list. The highest implicit or explicit index establishes how many matrices will be included in the file. The same MW may be included more than one time. Example: MO=1-5,11-15,MO[20]=1,MO[6]=31 establishes that 20 matrices will be written. Nine of the matrices (11-19) will be dummy because no data was entered for them. The output matrices are numbered monotonically beginning with 1.
MATO - NAME - |SV| - Specifies the names for the TP+ and CUBE Voyager matrices. Each MO does not require a name, but including names helps document the file. Valid matrix names only contain alphanumeric characters, spaces, and underscores (_). CUBE Voyager programs reading the file can reference the matrices by name and/or number.
NETO - |F| - Specifies the file name for the NETO; there must be NETO if assignment is being performed. The NETO can be a binary CUBE Voyager/TP+ network. Alternatively, NETO can point to a CUBE geodatabase network stored in an MDB file (personal geodatabase) or GDB (file geodatabase) by designating the file name followed by a backslash and the CUBE geodatabase network name. Note

Note: Networks stored in personal (MDB) geodatabases are limited to a maximum of 255 fields, including the default geodatabase network fields (OBJECTID, SHAPE, SHAPE_LENGTH, A, B, GEOMTERYSOURCE, etc).
NETO - APPEND - |I| - Specifies that the variables that are appended to NETO will have their assignment number set to this value. APPEND=5would cause V, VC,TIME,V1… to be named V_5, VC_5, TIME_5, V1_5, etc.
NETO - DEC - |I| - Specifies the number of decimal places to written to the NETO Volume fields. Values in the range 1-5 are valid.
NETO - EXCLUDE - |S20| - Specifies that the NETI variables that have names ending with the specified strings are to be excluded when copying NETI records to NETO. Thus, EXCLUDE=_1 will exclude all the first assignment variables. EXCLUDE=T_ is a special value that can be used to specify that the A-B and B-A values are NOT to be summed and included in the link records.
NETO - INCLUDE - |S20| - Specifies that certain new variables are to be included in the NETO file. The intent of this keyword is to allow the user to compute LW.vars and selectively include them in the NETO. All LW.vars named by this keyword will appear in the NETO as LW_NAME_# (# is the assignment number value). You can specify a single variable with INCLUDE, but this only adds a variable that has the same value in each record. The variable will appear as name_# in NETO.
PATHO - |F10| - Specifies the name of a file upon which paths from a PATHLOAD statement are to be written.
PATHO - COSTDEC - |I| - Specifies how many decimal places are to be maintained in the cost values when they are written to the PATHO file. The link cost values will be rounded to this many decimal places; this allows for more efficient compressing of the data. The value must range from 1-5. Default value is 2.
PATHO - ITERS - |I| - Indicates which iterations to write the PATHO file. Possible values are: + 0 - All iterations + 1 - First iteration only + 2 - Last iteration only + 3 - First and last iteration only

Default is 0.
PRINTO - |KF| - Specifies the name of the file where the output from a PRINT statement is to be directed using PRINT.

PRINTO=#
PRINTO - APPEND - |?| - See APPEND under PRINT.
SUBAREAMATO - |KF| - Specifies the file where binary matrices of values from subarea processing are to be written. The matrices on the file will be the final combination of values from all iterations. The number of matrices will be set by the highest PATHLOAD SUBAREAMAT[] index. The zonal configuration for the O/P matrices will be based upon the renumbering scheme obtained from the FILEI SUBAREANETI file.
SUBAREAMATO - DEC - |SV20| - Specifies the maximum number of decimal places to retain in the SUBAREAMATO matrices. The values may be 0-9, S for a single-precision number, or D for a double-precision number. If not specified, or any other value is coded, the values will default to 2. This keyword is ignored if the format is not TPP.
SUBAREAMATO - FORMAT - |C| - Specifies the desired output format for SUBAREAMATO matrices. Possible values are TPP, MINUTP, and TRANPLAN; if anything else is specified, or it is not specified at all (normal), the default is TPP.
SUBAREAMATO - NAME - |SV20| - Specifies the individual names for the SUBAREAMATO matrices. This keyword is ignored if the format is not TPP.
TOLLVOLO - |FV20| - Specifies the filenames for the TOLLVOLO files to store the toll gate to toll gate trips. If the name is a geodatabase table, then the output will be a database table in the geodatabase and the FORMAT keyword value will be ignored. See Example 11: Using TOLLMATI and TOLLVOLO.
TOLLVOLO - DEC - |SV*255| - Specifies the decimal settings for the matrix tables for MAT format or the setting for the TRIPS field for the other formats. The default is 2. For matrix format, there is a separate DEC for each MO. The value can be a number between 0 and 9 (the number of preserved decimals), or the character D or S for double and single precision floating point values. Care must be taken to match up the list of MO and the list of DEC, especially when wildcard characters are used in the MO specifications, which can generate multiple tables from a single MO specification and will require multiple matching DEC.

For database and text format, only the first DEC value (DEC [1]) is used. It is the number of decimal places that the TRIPS values are printed with.
TOLLVOLO - DELIMETER - |S| - Delimiter character that is written in a delimited TXT file. If this keyword is specified, the file will be delimited with this character. If it is not specified, the file will be fixed- field format.
TOLLVOLO - FORMAT - |S| - Specifies the format of the TOLLVOLO file:
- TXT (default) - ASCII text format either in fixed format or delimited (if DELIMITER is specified). There is no header for this file; each record contains the fields:
  - oONGATE - the on gate number as coded in the network link.
  - oOFFGATE - the off gate number as coded in the network link.
  - oONLINKA - The on gate link A node.
  - oONLINKB - The on gate link B node.
  - oOFFLINKA - The off gate link A node.
  - oOFFLINKB - The off gate link B node.
  - oMATINUM - The TOLLMATI number specified in the PATHLOAD statement.
  - oTOLLSET - The toll set number specified in the PATHLOAD statement.
  - oPATHSET - The TOLLPATHSET number specified in the PATHLOAD statement.
  - oVOLSET - The VOL set number specified in the PATHLOAD statement.
  - oTRIPS - The number of toll trips in this group.
All fields except the ONGATE, OFFGATE and TRIPS field can be omitted by specifying a ‘-‘ in the NAMES keyword for that position.

If MULTITOLL is set to true,
- Then there could be multiple on-gate and off- gate columns corresponding to the maximum number of toll gate pairs, the toll trips use.
- The On-Off gate pair columns will appear at the end and not at the start
- ONLINKA, ONLINKB, OFFLINKA and OFFLINKB will not be included.
- DBF - a standard DBF file will be written with each record containing the same fields as listed in the TXT format. The names of the fields can be changed from the default name with the NAMES keyword by position (e.g. NAMES[3] is the name for the ONLINKA field). All fields except the ONGATE, OFFGATE and TRIPS field can be omitted by specifying a "-" in the NAMES keyword for that position.
- MAT - Standard CUBE Voyager or TP+ matrices.
TOLLVOLO - INCLUDE0 - |?| - A flag that when set true indicates that records with 0 trip value will also be written to the file. The default value is false.
TOLLVOLO - MOMO - |SV255| - Specifies the toll trip matrices that are to be included in the TOLLVOLO file. This keyword is applicable only if the output format is MAT. The MO keyword should not be indexed because by using wildcard characters, multiple output tables can be generated. The toll trip groups are identified by 4 key values: TOLLMATI, TOLLSET, PATHSET and VOLSET. The format for the MO specification is M#T#P#V#. The # character can be a number for a specific set or can be a ‘?’ for a wildcard character. For example, M1T2P3V4 specifies the output of the group TOLLMATI 1, toll set 2, path set 3 and VOL set 4. If the specification includes one or more wildcard characters, all groups matching the specification will be output in separate tables. For example, M2T?P3V? specifies all groups from TOLLMATI 2 and path set 3 will be output to the matrix file. If the run has the groups M1T2P3V4, M2T2P3V4, M2T3P3V5, M3T2P3V4, then the M2T?P3V? specification will include the M2T2P3V4 and M2T3P3V5 tables in the output file. However, wildcard table inclusions are constrained by the TOLLMATI, TOLLSETS, PATHSETS and VOLSETS specifications. The same MO specification may be included more than one time.

The default for MO is M?T?P?V?, which will include all groups (up to a maximum of 255 tables) in the output file subject to TOLLMATI, TOLLSETS, PATHSETS and VOLSETS selections if they are specified.
TOLLVOLO - MULTITOLL - |?| - Outputs all on gate-off gate pairs, if a toll trip set goes through more than one set of gate pairs. If set to true, the output file will contains the fields: MATINUM, TOLLSET, PATHSET, VOLSET, TRIPS, ONGATE1, OFFGATE1, ONGATE2, OFFGATE2 … etc. up to highest on/off gate pairs found in the data. The default is false. The MULTITOLL keyword works in all text and database output format but will be ignored in matrix format output.
TOLLVOLO - NAMES - |SV255| - Specifies the names for the matrix tables for MAT format or the field names for the other formats. For matrix format, the list of NAMES will match the MO specification by position. If not specified, the default name for a matrix table is M#T#P#V#. The ‘#’ character represents the specific set numbers for that table. Care must be taken to match up the list of MO and the list of NAMES, especially when wildcard characters are used in the MO specifications, which can generate multiple tables from a single MO specification and will require multiple matching NAMES. If in doubt of how many tables may be generated from a wildcard specification, use the default NAMES instead.

For database output format (DBF and geodatabase), the list of NAMES is the user specified names of the 11 output fields. The default names are: ONGATE, OFFGATE, ONLINKA, ONLINKB, OFFLINKA, OFFLINKB, MATINUM, TOLLSET, PATHSET, VOLSET, TRIPS. All fields except the ONGATE,OFFGATE and TRIPS field can be omitted by specifying a ‘-‘ in the NAMES keyword for that position. For example, NAMES=OnNum, OffNum, -, - , -, - will name the first two fields as OnNum and OffNum instead of ONGATE and OFFGATE and omit the next 4 fields (ONLINKA, ONLINKB, OFFLINKA, OFFLINKB) in the output table. The order of the names should correspond to the original order of the 11 fields irrespective of whether MULTITOLL is true or false.

For text output format, the list of names are not used in the output file but the ‘-‘ name specification can still be used to omit certain fields in the output record.
TOLLVOLO - OFFGATES - |IVP1000| - List of off gate numbers that will be included in the output file. If this keyword is not specified, then by default, all OFFGATES will be output.
TOLLVOLO - ONGATES - |IVP1000| - List of on gate numbers that will be included in the output file. If this keyword is not specified, then by default, all ONGATES will be output.
TOLLVOLO - PATHSETS - |IVP1000| - List of path set numbers that will be included in the output file for all formats except MAT. For MAT format, the list will control the inclusion of output tables when wildcard characters are used in the MO specification. If this keyword is not specified, then by default, all PATHSETS will be output.
TOLLVOLO - TOLLMATI - |IVP10| - List of TOLLMATI numbers that will be included in the output file for all formats except MAT. For MAT format, the list will control the inclusion of output tables when wildcard characters are used in the MO specification. If this keyword is not specified, then by default, all TOLLMATIs will be output.
TOLLVOLO - TOLLSETS - |IVP10| - List of toll set numbers that will be included in the output file for all formats except MAT. For MAT format, the list will control the inclusion of output tables when wildcard characters are used in the MO specification. If this keyword is not specified, then by default, all TOLLSETS will be output.
TOLLVOLO - VOLSETS - |IVP1000| - List of VOL set numbers that will be included in the output file for all formats except MAT. For MAT format, the list will control the inclusion of output tables when wildcard characters are used in the MO specification. If this keyword is not specified, then by default, all VOLSETS will be output.
TREEO - |KS8| - Specifies the output file name where the results of shortest path trees may be stored. Up to 8 files are allowed.

See more on TREEO from Example 10: Shortest Path Trees Using TREEO.
TREEO - ALTNODEFIELD - |S| - Optional. Specifies if the alternative node number is to be written in the output file.
TREEO - APPEND - |?| - Optional. Flag indicating whether to overwrite or append to the output file. Possible values:
- T - Append the data to the specified file.
- F - Overwriting the existing file when writing the data.
TREEO - CELLTYPE - |I| - Specifies the cell values in the output file. Possible values are:
- 0 - link number (default)
- 1 - node number
- 2 - sequence node number
- 3 - alternative node number
TREEO - DELIMETER - Delimiter character for CSV file output. Default value is ‘,’.
TREEO - FORM - |I| - Specifies maximum field width for columns. Up to 3 values are allowed under FORM. These three values specify the field width for path set name, origin nodes and cell values (columns) respectively.

e.g.,FORM=4,6,7
TREEO - FORMAT - |S| - Specifies the format of the TREEO file. Possible values are TXT (default) and CSV.
TREEO - LISTALTNODES - |?| - Flag that indicates if the program writes the node alternative number in sequential order in the output file. Default value is F. To print alternative node numbers, ORIGINTYPE should be set to 1 and ALTNODEFIELD specified.
TREEO - LISTCOLNUMS - |?| - Flag that indicates if the program writes a row of column index in the output file. Default value is F.
TREEO - LISTNETNODES - |?| - Flag that indicates if the program writes the node number in sequential order in the output file. Default value is F.
TREEO - LISTLINKS - |?| - Flag that indicates if the program writes the information on all links in the network in the output file. Default value is F.
TREEO - MAXPERLINE - |I| - Specifies the number of column per line in the output file. If the number of columns defined by ROWTYPE is more than the MAXPERLINE, then the rows will be split into two or more lines. Also, the beginning cell index is added after the origin number and before the first cell value.
TREEO - ORIGINTYPE - |I| - Specifies if alternative zone number is to be listed in the output file instead of the original zone number. Possible values are
- 0 - original zone number (default)
- 1 - alternative zone number
Note: If set to 1, users must specify ALTNODEFIELD.
TREEO - ROWTYPE - || - Specifies the number of columns for each origin (each record) in the output file. Possible values are:
- 0 - number of nodes (default)
- 1 - highest node number
- 2 - number of links
TURNPENO - |F| - Specifies the file name where the movement delays from the junction model and/or the turn penalties from the turn penalty file will be written. In order to get the final travel time and cost skims from an assigned network it is necessary to pass the loaded network back through the Highway program and build and skim the paths from the loaded network. The TURNPENO file allows the movement delays computed by the Junction Model to be included in the path skims by using the TURNPENO file from the assignment as the TURNPENI file for the skims.

The data structure is the same as that of the TURNPENI file but a comment field is added to indicate the movement is delay is from the junction model in lieu of a turn penalty or restriction. An example of the output is show below.
```
2606 2621 2773 1 0.08 ;junct
2635 2621 2606 1 0.15 ;junct
2635 2621 2615 1 0.15 ;junct
2635 2621 2615 2 -1.00
2635 2621 2773 1 0.15 ;junct
```
TURNVOLO - |F| - Specifies the filename where the turning volumes are to be written. There may be more than one TURNVOLO specified; each may have a different format. Users must also specify TURNS to instruct program to accumulate turning volumes, otherwise, the TURNVOLO will be empty. The default format for this file is binary so that CUBE can display it directly. Please note that the presence of the VARS keyword may alter the overall application of this statement.

See Example using TURNVOLO.
TURNVOLO - DEC - |I| - Specifies the number of decimal places to preserve when the file is either DBF of TXT.
TURNVOLO - DELIMETER - |c| - Character that is written in a TXT file. If this keyword is specified, the file will be delimited with this character. If it is not specified, the file will be fixed-field format. If the value is a character, it should be enclosed within quotes; but it may also be specified as a number that represents the desired character (for example, 9=TAB).
TURNVOLO - FORMAT - |S| - Specifies the format for the file (must be BIN, DBF, or TXT).

Note: FORMAT=BIN will automatically be reset to TXT if VARS= is specified on the statement.
- BIN - Binary format that is usable only by CUBE. The structure is:
  - One header record (at least 64 bytes long):
    
    0-1 total length of this record (bytes)
    
    2-3 length of each turn record
    
    3-6 bits whose position represents the presence of a turn volume
    
    0: 1 always on for T0
    
    1: 1 if T[1] in the data records, 0 if not in data record
    
    2: 1 if T[2] present, o if not
    
    3-31 same for T[3]…
    
    7-64 CUBE Voyager TURNVOL pppp.nnnn HIGHWAY date…
    
    pppp is the CUBE Voyager project prefix
    
    nnnn is the CUBE Voyager sequence number
  - Individual records (length set in header):
    
    0-1 Anode
    
    2-3 Bnode
    
    3-4 Exit Node
    
    5-12 T[total] All Ts are double precision 13-201st T (T1)
    
    21-282nd T
- DBF - A standard DBF file will be written with each record containing the Anode, Bnode, ExitNode, T[0], and any appropriate T# values. The DBF header will name the variables that are in the data records.
- TXT - ASCII format either in fixed format or delimited. There is no header for this file; the structure of each record is:
  - Anode, Bnode, ExitNode, T,T# — (The user has to know which individual Ts are written to the file). The T values will be determined either by the DEC keyword, or internally by the program. Each volume will be formatted appropriately. If DELIMITER is specified, the fields will be written with only the delimiter separating them. If no DELIMITER, the fields will be in fixed width format; the program will determine the size. Note that VARS= will cause this format to change.
TURNVOLO - INCLUDE0 - |?| - Flag that when set false indicates that a turn movement with T values all equal to 0, is to not be written to the file. The default value is true.
TURNVOLO - NAMES - |S25| - May be used if both VARS= and FORMAT=DBF are specified. The names are aligned with the VARS fields and then placed into the created dbf file. Optionally, the NAMES may be indexed [] to set the alignment for renaming only specific variables.
TURNVOLO - QUEUEDATA - |?| - Flag that indicate if the statistics of the intersection modeling is to be written out into the DBF file. If it is set to true, it must be used combined with FORMAT=DBF. Eight extra columns (INITQ, FINALQ, QFLOW, CAPACITY, RANDOMNESS, DELAY, FLOW0DELAY AND LOS) will be written into the DBF file. Default value is false.
TURNVOLO - VARS - |S25| - Specifies which variables are to be written to the file. Note that if VARS is specified, FORMAT=BIN will be reset to FORMAT=TXT, or if there is no FORMAT specified, that it will default to TXT. Any of the following variables may be specified (in any order, and may even be repeated): A B C T T1 T2…Tn, where n is the highest VOL in the application. Optionally, the variable name may have a standard PRINT form appended to it (enclosed within parenthesis). If decimals are to be printed with the values, it is suggested that an appended format be specified instead of DEC=. If a delimiter is desired, FORMAT=TXT, DELIMITER= must be specified.

PATHLOAD must include the keyword ESTMO=num, where num is between 1 and 20 corresponding the ICP file to write to, in order for the trips assigned from that statement to be included in the matrix estimation. There may be more than one PATHLOAD statement including ESTMO. It does not make sense to have ESTMO=num on a PATHLOAD statement that does not have VOL[]= on it. PATHLOAD must have the keyword PATHO=# in order to output the path file specified with FILEO PATHO=

Example using TURNVOLO

MATO=TPPTEST.MAT, MO=1-2, DEC=2*2 NAME=SLINK1,TOLL1,COMBINE=Y MATO[3]=DEMO12.DAT, FORMAT=MINUTP, MO=1,3,5-7
NETO=ALTERNATE.NET, EXCLUDE=_#1, _#2
TURNVOLO=AlternateA.Trn.Bin, format=BIN
TURNVOLO=AlternateA.Trn.DBF, format=DBF, DEC=0
TURNVOLO=AlternateA.Trn.TXT, format=TXT, DELIMITER=',', DEC=0
TURNVOLO=AlternateA.Trn.TXT, VARS=b(5) a(6) c(6) t(10.2) t1(10.2) t2(8.2)
TURNVOLO=AlternateA.Trn.TXT, format=dbf, vars=a(5),b(5),c(5),t(8.2),
t1(8.2),t2(8.2), names= Enter thru exit Total Cars Trucks

Example using multiple output screenline data files (DAT), and output intercept files (ICP)

RUN PGM=HIGHWAY
FILEO ESTMDATO[05] = NewSL22NF.DAT, LINKTOICP=7,
      ESTMDATO[10] = NewSL24NF.DAT, LINKTOICP=17,
      ESTMDATO[12] = NewSL23NF.DAT, ; default to match ESTMICPO[12]
      ESTMICPO[02] = NewSL21NF.ICP, countvar=li.count, FORMAT=1, ; new
                                                                 ; format
      ESTMICPO[07] = NewSL22NF.ICP, countvar=li.count, FORMAT=0, ; old
                                                                 ; format
      ESTMICPO[12] = NewSL23NF.ICP, countvar=li.cost, FORMAT=1,
      ESTMICPO[17] = NewSL24NF.ICP, countvar=li.cost, FORMAT=1
FILEO NETO = NEWLOAD.NET
FILEO NETI = dtown2.net

PAR  MAXITERS=5

PROCESS PHASE=LINKREAD
  IF (LI.SPDCLASS=33) ADDTOGROUP=1
  IF (LI.SPDCLASS=45) ADDTOGROUP=2
  IF (LI.SPDCLASS=55) ADDTOGROUP=3
ENDPROCESS

PROCESS PHASE=ILOOP
  MW[1]=10
  MW[2]=20
  MW[3]=30
  MW[4]=40
  PATHLOAD PATH = COST, VOL[1]=MW[1], EXCLUDEGROUP=1, ESTMO=2
  PATHLOAD PATH = COST, VOL[2]=MW[2], EXCLUDEGROUP=2, ESTMO=7
  PATHLOAD PATH = COST, VOL[3]=MW[3], EXCLUDEGROUP=3, ESTMO=12
  PATHLOAD PATH = COST, VOL[4]=MW[4],                 ESTMO=17
ENDPROCESS
ENDRUN

Example

MATO=TPPTEST.MAT, MO=1-2, DEC=2*2 NAME=SLINK1,TOLL1,COMBINE=Y
MATO[3]=DEMO12.DAT, FORMAT=MINUTP, MO=1,3,5-7
NETO=ALTERNATE.NET, EXCLUDE=_#1, _#2
TURNVOLO=AlternateA.Trn.Bin, format=BIN
TURNVOLO=AlternateA.Trn.DBF, format=DBF, DEC=0
TURNVOLO=AlternateA.Trn.TXT, format=TXT, DELIMITER=',', DEC=0
ESTMICPO=ESTMO.ICP, VAR=LI.COUNT, SCREENLINE=LW.SCREENLINE
ESTMDATO=ESTMO.DAT, NAME='SL#1','SL#2','SL#3', NAME[5]='SL#5'

; The ESTMDATO and ESTMICPO keywords will not need an index because
; they default to index 1. However, the PATHLOAD ESTMO keyword value
; will have to be changed from "T" to "1" for the script to work.

Example

/*
Commands to generate a path file.
*/
FILEO PATHO[1]=myfile.pth, costdec=2, iters=0
.
.
.
PATHLOAD PATH=TIME, PATHO=1, INCLUDECOST=F, NAME=TIME_PATH, ALLJ=T

QUEDATA Example

RUN PGM=HIGHWAY
FILEI TURNPENI = "myTurnPen.pen"
FILEO JUNCTIONO = "myJunOut.INT"
FILEO TURNVOLO="myTurnOut.DBF",FORMAT=DBF, QUEUEDATA=T FILEO NETO = "myLoaded.NET"
FILEI JUNCTIONI = "myJunctions.ind",
   period=60,set=1
FILEI NETI = "myBase.net"

PARAMETERS COMBINE = AVE
PARAMETERS RELATIVEGAP=0.0001 GAP = 0.0, MAXITERS=10
PARAMETERS AllowAllUTurns=T ;model U-turns movements at all nodes unless
it is banned in the Junction file

ZONESMSG=1
TURNS N=1-99999

PROCESS PHASE=LINKREAD
   C = LI.CAP
ENDPROCESS

PROCESS PHASE=ILOOP
    MW[1]=500
    PATHLOAD PATH = TIME, VOL[1]=MW[1], PENI=1,2
ENDPROCESS

PROCESS PHASE=ADJUST

FUNCTION {
   V=VOL[1]
   TC = T0 *(1+0.18*(V/C)^8.5)
}
ENDPROCESS
ENDRUN/*
Commands to generate a path file.
*/
FILEO PATHO[1]=myfile.pth, costdec=2, iters=0
.
.
.
PATHLOAD PATH=TIME, PATHO=1, INCLUDECOST=F, NAME=TIME_PATH, ALLJ=T

Output of DBF file:

FILET

Specifies where the Highway program writes various temporary files.

Keywords include:

FILET keywords

PATH - |S| - Specifies the path to the disk area where any temporary files are to be written.
DISTRIBPATH - |S| - Specifies the temp file folder for an intra-distribution run. This is to speed up run time when multi-steps are distributed to different machines but the distributed steps will do intra distribution to slaves on the same machine. This avoids using a network drive to pass data between the slaves and the main process. The option defaults to the working directory. The restriction on that is both the main and the slaves must be referencing the same location, either on a local drive that both the main and the slaves can access (basically the main and the slaves must be on the same machine), or a network drive that are mapped to the same drive letter for both the main and the slaves.
ESTPATH - |S| - Specifies the file path for saving the temporary ESTM files when doing intra distribution. Similar to the FILET DISTRIBPATH keyword, the ESTMPath keyword defaults to the working directory. The restriction on that is both the main and the slaves must be referencing the same location, either on a local drive that both the main and the slaves can access (basically the main and the slaves must be on the same machine), or a network drive that are mapped to the same drive letter for both the main and the slaves. The specified folder must already exist or else the specification will be ignored and the temp file will be written to the working directory.

The value for PATH is entered as a standard operating system path. If not specified, it will default to the path in the environment variable named TMP, or TEMP. The logic for determining the appropriate path, and opening the files is:

If the PATH=’ ‘, use current directory.
If the PATH is specified, use it.
If not specified, and TMP is, use TMP.
If the operation fails, Fatal.

Example

PATH=' ' ; use current directory
PATH=..\ ; up a directory
PATH=c:\ ; root of c:

FILLMW

Fills work matrices.

See FILLMW for a complete description.

FUNCTION

Defines special functions.

Keywords include:

Use FUNCTION statements to enter single expressions for computing certain values. The statements are inoperable by themselves, and can be anywhere in the input stream, the program dictates when they will be processed. It is recommended that they be placed prior to the first PHASE statement or within the major phase in which they will be processed. If there is no function for a type, a default function will be used. The V function may be defined one time only. Each of the other functions is entered with an index [] to indicate which LinkClass it is to be applied to. All the functions can be on one FUNCTION statement, or they can be on individual statements, or some combination of both. To reduce confusion, some users may wish to code the functions on a single FUNCTION statement with a block control.

FUNCTION keywords

COST - |NV999| - Computes the cost for a link. COST is processed in the LINKREAD and ADJUST phases to compute the cost. In LINKREAD, it is applied after the stack statements.

In the ADJUST phase, it is applied during capacity restraint, usually following a TC application, and after the user stack statements are completed. This is the only way to alter the cost values.
Note:
- LW.xxx equations containing variables which are a function of Volume changes (such as TIME) cannot be used with FUNCTION COST when standard equilibrium processing is used (COMBINEEQUI). Such arrays are updated following the equilibrium processes in the ADJUST phase, and will generate incorrect results if directly referenced in FUNCTION COST. Instead, the LW variables must be replaced with their formula from the cost function definition. For example:
  
  Wrong Usage:
```
LW.Temp=TIME + dist_fac*li.distance
COST= LW.Temp *2
```
  Correct Usage:
```
LW.Temp= dist_fac*li.distance
COST= (TIME + LW.Temp) *2
```
  For an implementation example, Bentley recommends reviewing Multiple user class assignment using generalized cost functions.
- When referencing individual volume sets in FUNCTION COST, V1, V2, etc, must be used instead of VOL[1]. VOL[2], etc. For an example, please see Multiple user class assignment using generalized cost functions.
- If FUNCTION COST is not defined, Highway will use TIME as the cost for the calculation of convergence, and for the computation of Lambda for the Frank-Wolfe algorithm (COMBINEEQUI).
TC - |NV999| - Computes the congested time on a link by LINKCLASS. TC functions are the labels in the software given to volume delay functions (commonly referred to as VDFs). TC stands for congested time. The LINKREAD phase of this program allows the user to associate every link in the network with an internal LINKCLASS variable. The TC functions can be indexed by LINKCLASS to specify different volume delay relationships for different classes of facility. If no LINKCLASS is defined for a link it defaults to LINKCLASS=1. If no TC functions are defined then a default TC function is applied. The default TC function is the standard BPR with the form:

TC[1] = T0 *(1 + TCCOEFF * (V/C) ^ TCEXP)

where TCCOEFF defaults to 0.15 and TCEXP defaults to 4 if values are not specified with PARAMETERS. Specifying TC[1] alters the function. The user can also code their own functional form if the BPR form is not what is desired. In general,

TC[#]=f(T0, V/C, TCCOEFF, TCEXP) but the user is free to experiment with any forms that make sense to them for their application.
Note:
- If individual volume sets are required for TC functions, then V1, V2, etc must be used instead of VOL[1], VOL[2], etc. Otherwise, the results will be incorrect.
- When computing Lambda for the Frank-Wolfe algorithm (COMBINEEQUI), any LW variables (such as TIME) which are a function of volume change should not be directly referenced in TC functions; the results will be incorrect. Instead, the same formulas used to generate the work variables should be employed within FUNCTION COST.
V - |N| - Computes the total volume on a link after an iteration. It is applied in the ADJUST phase. If there is no V function, V is assumed to be the sum of all the VOL sets (V[1] + V[2] + … + V[n]). Some times the total volume should not be the sum of all the VOLs. For example: if a separate select link VOL set is being accumulated in addition to the total VOL set, that VOL set should be excluded from the total volume. Another example would be if one of the VOL sets is for a vehicle type for which it is desired to equate to a passenger car equivalent.

Note: When using multiple volume sets, FUNCTION V must reference VOL[1], VOL[2], etc, and not V1, V2, etc, to obtain correct results. For an implementation example, Bentley recommends reviewing Multiple user class assignment using generalized cost functions.

Example

FUNCTION {
V = VOL[1] + VOL[3] + VOL[10]*1.3
TC[1] = T0 * (1 + 0.20 * (V/C) ^ 6)
TC[201] = MIN(T0*5, T0 * (1.5 + 0.18 * (V/C) ^ 4)) COST[255] = TIME * 2
}

GOTO

Jumps immediately to a named statement.

GOTO label

When GOTO is processed, flow immediately branches to the target statement, named :label. Each GOTO statement must have an associated :label statement. Use care when the :label statement is within a different IF or LOOP block. The target statement must begin with a colon (:).

Note: GOTO is not valid in the SETUP phase. You cannot place a :label statement inside a JLOOP statement. However, you can use a GOTO statement inside a JLOOP to jump to a :label statement outside the JLOOP.

Example

GOTO buildhwy
GOTO :buildhwy

Example

GOTO tolls
...
:tolls
...
IF (expression) GOTO :tolls
            ; It is permissible to go backwards.

IF … ELSEIF … ELSE … ENDIF

Performs certain operations based on conditions.

IF expression ELSEIF expression ELSE expression ENDIF

Use IF/ENDIF blocks to determine if certain operations are to be performed. IF blocks may be nested, but they may not overlap LOOP, JLOOP, or other IF blocks. If a variable in the expression is MI.n.name, ZI.n.name, or MW[], the same rules for indexing in a COMP statement are applied. MI.n.name or MW[] should realistically only be used within a JLOOP. Lengthy IF expression solutions could be time consuming; use them judiciously. Although IF expressions can be quite powerful for zonal selection, sometimes INCLUDE and EXCLUDE filters may provide a much more efficient selection process (see the examples below).

You may append the following control statements to a single IF statement:

Example

IF (LI.DIST< 20) LIST=a,b,LI.dist; single IF with process
IF (expression) EXIT

IF ( ( j=3-5,6-30,57 & k=(2*j-4) ) || ((J*k) = 14-20,56) )
.
ELSEIF (loop_cntr > 10)
.
ELSEIF (loop_cntr > 5 && diff.time < 32)
.
ELSE
.
ENDIF

JLOOP … ENDJLOOP

Controls a loop through the columns of a matrix row.

Keywords include:

Each row represents an origin zone and each column represents a destination zone. Typically, you use JLOOP … ENDJLOOP blocks for matrix computations that you cannot complete with a single COMPMW control statement.

JLOOP blocks may not be nested, and may not overlap other JLOOP, LOOP, or IF blocks.

JLOOP keywords

J - |I| - Optional. List of up to three integers that define the value of the loop control variable. You may define each integer with an expression. Specify as:
```
J=Jbeg, Jend, Jinc
```
where:
- Jbeg defines the initial value of the loop’s control variable, J. Default value is 1. If you do not define Jbeg, you cannot define Jend or Jinc. In that case, Jend defaults to the number of zones in the network, and Jinc defaults to 1.
- Jend defines the terminal value of the loop’s control variable, J. Valid values range from 1 to the network’s maximum number of zones. If not specified, Jend defaults to Jbeg, and Jinc defaults to 1.
- Jinc defines the increment for the loop’s control variable, J. If not specified, set to 1 or -1, depending on the direction from Jbeg to Jend.
EXCLUDE - |I| - Optional. List of origin zones that the program will not process. If you include this keyword, the program will not process statements for these zones, and instead skip to the next zone.
INCLUDE - |I| - Optional. List of origin zones that the program will process. If you include this keyword, the program will only process statements for these zones.

A JLOOP block causes the program to loop between the JLOOP statement and its ENDJLOOP statement, moving J from Jbeg to Jend in increments of Jinc. The logic for JLOOP and ENDJLOOP processing is:

At JLOOP:

If J is specified, establish values for Jend and Jinc, else set J=1, Jend=Zones, Jinc=1.
If (J < 1 or J > Zones or Jend <1 or Jend > Zones), terminate fatally.
If (statement contains INCLUDE keyword and J is not listed among INCLUDE keyword values) go to ENDJLOOP.
If (statement contains EXCLUDE keyword and J is among listed EXCLUDE keyword values) go to ENDJLOOP.
Process statements within JLOOP.

At ENDJLOOP:

Add Jinc to J.
If (Jinc > 0 and J <= Jend) go to statement following JLOOP.
If (Jinc < 0 and J >= Jend) go to statement following JLOOP.
Control passes to statement following ENDJLOOP.

The program processes all statements between the JLOOP and ENDJLOOP statements, including COMP MW statements, with the current value of J.

The following statements are valid within a JLOOP block:

Note: You cannot place a :label statement inside a JLOOP; a GOTO statement cannot jump into a JLOOP. However, you can place a GOTO statement inside a JLOOP to jump to a :label statement outside the JLOOP.

Example

;process only intra zonal values, but exclude externals
JLOOP J=I EXCLUDE 500-535
   ...
ENDJLOOP
ROWSUM1 = 0 ROWSUM3=0
JLOOP     ; get rowsums for matrices
   ROWSUM1 = ROWSUM1 + MW[1]
   ROWSUM3 = ROWSUM3 + MW[3]
ENDJLOOP

LINKLOOP … ENDLINKLOOP

Controls a link loop for processing link records in the ILOOP phase. LINKLOOP serves as a shorthand for a LOOP statement iterating through available links with a user-defined index (see Example 1 below).

By default, the link loop processes through all link records at an increment of one. You can use LINKNO, the default loop index, to reference the current link number. The program supplies all link arrays the default [LINKNO] in a LINKLOOP block.

Note: You can nest LINKLOOP blocks within other blocks such as IF or LOOP, but not another LINKLOOP. You cannot overlap them with IF blocks.

Example 1

; Print each Link’s number and Distance
LINKLOOP
   PRINT LIST="LINKNO=", LINKNO," LI.DISTANCE=",LI.DISTANCE
ENDLINKLOOP

; Equivalent to this LOOP block:
LOOP k=1,NUMLINKS
   PRINT LIST="LINKNO=", k," LI.DISTANCE=",LI.DISTANCE[k] ;note [k] index
ENDLOOP

Example 2

; double LW.VAR for even number zones
IF (I%2==0)
   LINKLOOP
      LW.VAR=LW.VAR*2 ; no [LINKNO] subscript needed
   ENDLINKLOOP
ENDIF

LOOP...ENDLOOP

Controls a general variable loop.

LOOP Lvar=Lbeg,Lend,Linc
...
ENDLOOP

where:

Lvar — Name of the loop control variable. Lvar is not protected during the loop; computational, program, and other LOOP statements can alter its value. Lvar must be followed by Lbeg, and optionally, Lend and Linc.
Lbeg — Numeric expression that initializes Lvar.
Lend — Optional. Numeric expression that Lvar is compared to when processing the ENDLOOP statement. If not specified, no comparison is made and loop ends at ENDLOOP statement.
Linc — Optional. Numeric expression added to Lvar before making the ENDLOOP comparison. If not specified, Linc is set to 1 (or -1 if Lbeg and Lend are both constants and Lbeg < Lend; a backwards loop).

Use LOOP…ENDLOOP blocks to repeat a series of statements. LOOP initializes a variable; ENDLOOP compares the contents of the variable to another value, and branches back to the statement following the LOOP statement if the comparison fails. You can nest LOOP blocks, but you can overlap them with IF blocks. The process differs considerably from JLOOP. The logic is as follows:

At LOOP:

Initialize Lvar to Lbeg.
Drop through to next statement.

At ENDLOOP:

If Lend not specified, jump to next statement.
Compute Lend.
If Linc not specified, set Linc to 1 or –1(if Lbeg and Lend are constants, and Lbeg > Lend), otherwise compute Linc.
Add Linc to Lvar.
Compare Lvar to Lend.
If (Linc > 0 and Lvar > Lend) jump to statement after ENDLOOP
If (Linc > 0 and Lvar <= Lend) jump to statement after LOOP
If (Linc < 0 and Lvar < Lend) jump to statement after ENDLOOP
If (Linc < 0 and Lvar >= Lend) jump to statement after LOOP

This logic offers considerable flexibility, but can result in unpredictable results or endless loops. Endless loops could happen if the Lend and/or Linc values are expressions that contain variables that could change during the loop. On the other hand, the flexibility provides for powerful control. The loop will be processed at least one time regardless of Lend and Linc values. Most uses will involve constants. Because Lvar values can be expressions, Lbeg, Lend, and Linc must be separated by commas (standard white space delimiting cannot be interpreted properly).

Example 2

LOOP pass=1,10 ; perform 10 passes
...
ENDLOOP
LOOP xyz=abc*def,ghi+jkl,mno/pqr
   LOOP abc=xyz,xyz+2,2 ; nested LOOP ...
   ENDLOOP
ENDLOOP
LOOP jj=10,3,-2.5 ; 10, 7.5, 5.0
...
ENDLOOP

PARAMETERS

Sets general parameters.

Keywords and sub-keywords include:

AAD
ALLOWLAMBDA0
ALLOWALLUTURNS
ALLOWUTURNS
CAPFAC
COMBINE
- BiFWVERSION
- ENHANCE
- FRACTIONS
- LAMBDASEARCH
- LINKRANDSERIES
- MEMORY
- MULTITHREAD
- STOCHASTICSEED
- VARIABLEDEMAND / ALLJ
- WEIGHTS
CONSOLIDATE
DISTRIB_ESTM
DP_COMBINEPATH
DP_KEEPPATHFILE
EQUITURNCOSTFAC
GAP
MATOADJUST
MAXITERS
MAXMW
MAXSTRING
MAXVARS
MODELPERIOD
PDIFF
PDIFFVALUE
RAAD
RELATIVEGAP
RMSE
TCCOEFF
TCEXP
TURNCOSTFAC
TURNGAPWT
USE_V_ONLY
ZONEMSG
ZONES
TRACESUMMARY

PARAMETERS keywords

AAD - |KR| - Specifies the cutoff point based upon the average absolute difference in volumes between two iterations.

Default value is 0.5. 2
ALLOWLAMBDA0 - |K?| - Allow LAMBDA values to go to zero. Default is True. If this option is set to true or left as default, then highway assignment iterations will stop once LAMBDA reaches zero, since no additional convergence can be achieved, once LAMBDA is zero. AllowLambda0 does not apply when LAMBDASEARCH=EQUATION.
ALLOWALLUTURNS - |?| - Option to allow U-turn at all nodes and assumes U-turn uses a shared-lane with left turn lane if this movement is not banned or prohibited in junction file and/or turn penalty file. If there are extra specification in junction file, then the local setting overwrites the global setting. EXAMPLE A:
ALLOWUTURNS - |?| - Option to allow U-turn at all nodes if this movement is allowed in junction file. Global U-Turn control settings and interaction with Junction file level controls and EXAMPLE B:
CAPFAC - |KR| - Specifies a value to convert input capacity to the same unit as V. It is not used if C is specified in the LINKREAD phase. When C is not specified in the LINKREAD stack and is obtained directly from the input network, C = CAPFAC * input capacity. (See LINKREAD phase for details on how CUBE Voyager obtains capacity from input network.)

Default value is 1.
COMBINE - |KS| - Specifies the method to combine the results of iteration volumes. Default value is EQUI.

Possible values include:
- EQUI - Equilibrium assignment. Iteration volumes are factored by the equilibrium weights computed for each iteration.
  
  For important details on usage, please see EQUI.
- AVE - Average all the iteration loadings. See AVE.
- WTD - Weighted Average assignment. Similar to AVE above, but the user can specify a specific weight for each iteration. See WTD.
- ITE - Iterative assignment keeps only last iteration volumes as output. See ITE.
- SUM - Sum assignment is one in which the final volumes are the result of adding the volumes from each iteration. This is traditionally known as incremental loading.
  
  For more information, see SUM.
- PATH - HIGHWAY includes support for path based assignment using a gradient projection algorithm.
  
  For details on usage, see PATH.
- PROBIT - Supports stochastic assignment.
  
  For important usage information, see PROBIT and BURRELL.
- BURRELL - Supports stochastic assignment.
  
  For important usage information, see PROBIT and BURRELL.
COMBINE - BiFWVERSION - |I| - Subkeyword used with COMBINE=EQUIENHANCE=2. This keyword enables compatibility of the Bi-conjugate Frank-Wolfe algorithm with CUBE Voyager 6.0.2.

Set BiFWVERSION=602 to enable the compatibility. Default value is 0.
COMBINE - ENHANCE - |I| - HIGHWAY supports additional assignment algorithms for the COMBINE=:ref:EQUI <hp-cs-param-combine-equi> mode. To access these, include this keyword immediately after the COMBINE=:ref:EQUI <hp-cs-param-combine-equi> statement. The values for this keyword are:
- 0 — Normal Frank-Wolfe algorithm (default)
- 1 — Conjugate Frank-Wolfe algorithm
- 2 — Bi-conjugate Frank-Wolfe algorithm
When ENHANCE=2 you may enable backwards- compatibility of Bi-conjugate Frank-Wolfe from CUBE Voyager 6.0.2 using the BiFWVERSION subkeyword; see BiFWVERSION.
COMBINE - FRACTIONS |RV*| - Specifies the fractions to be when COMBINE is set to SUM. The number of fractions sets the value for MAXITERS. The sum of all the values should be 1.00; if the sum is not 1.00, a warning message will be issued. That will not preclude the program from executing. During the ADJUST phase for each iteration, V will be factored according to the FRACTIONS for that iteration, and added to the V accumulated for the prior iterations.
COMBINE - LAMBDASEARCH - |S| - Specifies alternate methods for computing Lambda in EQUI processing.

You can select one of two Lambda search processes:
- AREA - Indicates to minimize the area under all the V vs. Cost curves computed for incremental estimates of lambda for every link. Appropriate when using a generalized cost function as depicted in Example 8: Multiple User Class Assignment with Cost based on User Class.
- EQUATION - Estimates lambda by solving an expression based on the TC functions.
  
  Available only with single user class assignment, and when using the default FUNCTION COST=TIME.
Default value is AREA.

Note: Both processes estimate Lambda so the results might be slightly different. See the description of these two processes in ADJUST phase.
COMBINE - LINKRANDSERIES - |?| - Switch to decide whether the random number generator will bind to the network or not. Only valid for COMBINE=BURRELL or PROBIT.
COMBINE - MEMORY - |?| - Sub-keyword used with COMBINE=EQUI and MULTITHREAD. This is a boolean key (T/F) and provides the option to write intermediate files from MULTITHREAD, to memory or to disk. Default is true.
COMBINE - MULTITHREAD - |I| - Sub-keyword used with COMBINE=EQUI. This keyword enables distributing the Adjust phase across multiple threads. Valid values range from 0 to 200. When using this parameter, any temp variables (variables other than LI, LW or built in variables like TIME, COST, TC, V, C, etc) referenced in the ADJUST phase, should be named beginning with an underscore (e.g. _VOT).
COMBINE - STOCHASTICSEED - |I| - Random seed to use for the stochastic process. If not set it will not set the seed number and will continue to use the current random series. If set to zero it will reset the seed with the current time to create a random starting point. Only valid for COMBINE=BURRELL or PROBIT.
COMBINE - VARIABLEDEMAND / ALLJ - |?| - The keywords VARIABLEDEMAND and ALLJ can be included immediately after the COMBINE=PATH statement, which gives additional flexibilities to handle complex scenarios. The values of the two keywords are T/F, and both of them default to false. If VARIABLEDEMAND is true, demands are allowed to change between iterations.

ALLJ only applies when VARIABLEDEMAND=T. If ALLJ is true, all destinations (J) are processed even if the demand is zero.
COMBINE - WEIGHTS - |RV*| - Specifies the weights to be used when COMBINE is set to WTD. The number of weights sets the value for MAXITERS.
CONSOLIDATE - |I| - Specifies minimum string length for link consolidation, if CONSOLIDATE=T is specified on the PATHLOAD statement. Default value is 2.

If the default is used (2), then links of two or more strings will be consolidated. If CONSOLIDATE is set to 3 then links of three or more strings will be consolidated, and so on.
DISTRIB_ESTM - |?| - Option to distribute the ESTM processing.
DP_COMBINEPATH - |?| - Option to combine the individual path files from each cluster node. Default value is true.
DP_KEEPPATHFILE - |?| - Option to keep the individual path file from each cluster node. Individual Cluster node path files are valid path files but only contain paths from the zonal range processed by that Cluster node. If DP_COMBINEPATH is true and DP_KEEPPATHFILE is true, the path files will be combined but the individual Cluster node path files will be kept as well. If DP_COMBINEPATH is false, then DP_KEEPPATHFILE will not apply, since the individual Cluster node path files will be kept regardless.
EQUITURNCOSTFAC - |KR| - Factor used to convert turn delays from minutes to cost for estimating Lambda in the equilibrium process. Default value is 0.

If the default value (0) is used, turning volumes and delays from JUNCTIONI processing are not included in the estimation. This value is used only if: there are turning volumes and COMBINE is set to EQUI. When use, this value typically specifies the same value as TURNCOSTFAC.
AP - |KR| - Specifies the cutoff point based upon the relative difference in system cost (volume * cost) between two iterations. Default value is 0.005. 2
MATOADJUST - |KI| - Specifies how often MATO matrices are combined during assignment (see COMBINE). Enter the number of iterations to combine at once, using the same factors used to combine volumes. Default value is 1 — the matrices are combined each iteration.

A lower number requires less disk space but more processing time. A higher number results in faster processing, but requires more disk space to store intermediate matrices. With a high number and numerous iterations, you could exhaust disk space.

Bentley recommends leaving this value at 1 (matrices will be combined after each iteration). If you wish to improve run times and disk space is not a concern, you may use a larger value such as 5.
MAXITERS - |KI| - Specifies maximum number of assignment iterations to be performed. Default value is 20 if COMBINE=EQUI; otherwise, the default value is 1. The highest allowed value is 1000 iterations. 2
MAXMW - |KI| - Optional. Maximum index for work matrices (MWs). Valid values range from 1 to 999. Default value is 999. Normally, you do not specify this keyword and override default value.
MAXSTRING - |KI| - Specifies the maximum length for a string variable. Default is 100. If you expect to compute longer strings, you must define a larger number. All string variables will have this possible length.

The maximum is 1000 characters.
MAXVARS - |KI| - MAXVARS configures the size of an internal buffer in Highway which holds user-defined variables.

Bentley recommends leaving MAXVARS unset unless a print file message (698) suggests it be increased. Default is 1000.
MODELPERIOD - |KR| - Duration of the model period in minutes. The input demand matrix should be in units of vehicles (or PCU) per model period. If no value is specified, a default of sixty minutes (one hour) will be used.

Note: This value is only used when junctions are being modelled, or during an AVENUE run. MODELPERIOD, when specified, takes precedence over the value of FILEI JUNCTIONIPERIOD.
PDIFF - |KR| - Specifies the cutoff point based upon the fractional portion of links that have a change in volume (between two iterations) less than the value of PDIFFVALUE. Default value is 1.00. 2
PDIFFVALUE - |KR| - Specifies the value to be used with PDIFF. Default value is 0.0. The default value of 0.0 will result in null PDIFF outputs since no links will satisfy the condition. 2
```
[ABS(V1-V2) / (V1)] < PDIFFVALUE
```
Where V₁ and V₂ are the link flows of consecutive iterations.
RAAD - |KR| - Specifies the cutoff point based upon the relative average absolute difference in volumes between two iterations. Default value is 0.005. 2
RELATIVEGAP - |KR| Specifies an alternative GAP measure as the cutoff point. Default value is 0.005. 2
RMSE - |KR| - Specifies the cutoff point based upon the root mean squared error of the differences in volumes between two iterations. Default value is 0.1. 2
TCCOEFF - |RV*| - Represents the coefficient term in a LINKCLASS- specific TC function relating congested volumes from the assignment to congested travel times on the links. Default value is 0.15.

TC functions are the labels in the software given to volume delay functions (commonly referred to as VDFs). TC stands for Congested Time or TC. The LINKREAD Phase of this program allows the user to associate every link in the network with an internal LINKCLASS variable. The TC functions can be indexed by LINKCLASS to specify different volume delay relationships for different classes of facility. If no LINKCLASS is defined for a link it defaults to LINKCLASS=1. If no TC functions are defined then a default TC function is applied. The default TC function is the standard BPR with the form:
```
TC[1]=T0 *(1+ TCCOEFF * (V/C) ^ TCEXP) 
		  
```
The default values for TCCOEF and TCEXP result in the Standard BPR formula. If you code LINKCLASS values but do not code alternative TC functions by LINKCLASS, the default BPR form will be used but the LINKCLASS-specific values of TCCOEFF and TCEXP (if coded) will be substituted into the formula for the LINKCLASS. For example, if four LINKCLASSes are defined in the LINKREAD phase, and no TC functions are specified then TC[1] as specified above is in effect for all links. If the user codes:
```
PARAMETERS TCCOEFF[1]=0.15, TCEXP[1]=4,
TCCOEFF[2]=0.16, TCEXP[1]=4.5,
TCCOEFF[3]=0.17, TCEXP[1]=6,
TCCOEFF[4]=0.18, TCEXP[1]=8,
```
Then these LINKCLASS-specific values of TCCOEFF and TCEXP are substituted into TC[1] for the appropriate LINKCLASS of a given link. This allows you to have one common functional form but apply different coefficient and exponent values by LINKCLASS. You can also code your own functional form if the BPR form is not what is desired.

In general, TC[#]=f(T0, V/C, TCCOEFF, TCEXP) but the user is free to experiment with any forms that make sense to them for their application.
TCEXP - |RV*| - Represents the exponential term in a LINKCLASS-specific TC function relating congested volumes from the assignment to congested travel times on the links. See the discussion for TCCOEFF above for usage. Default value is 4.0.
TURNCOSTFAC - |KR| - Factor to convert turn times to equivalent costs for use in summary statistics and GAP calculations. If the value is 0, the summary report will not include turn volume costs. Default value is 1.
TURNGAPWT - |R| - Constant that indicates how much weight each turn movement should have when turn cost is used in GAP calculations. Default value is 1.

A value of 1 indicates that each movement is to be considered with the same weight as a link. A value of 2 indicates that the turn cost should be multiplied by 2 (each turn movement is to be considered equal to 2 links during testing).
USE_V_ONLY - |K?| - Option to stop computing all the individual volume sets, when in the adjust phase, to speed up the run when individual volume sets are NOT used in the TC and COST functions. Default is false, so each volume set volumes are processed to make the individual set combined volume (V1, V2 etc.) available to the TC and Cost functions. These are generally not needed except for some generalized cost model that use the individual volumes instead of the total volume. If a large number of volume sets are used, it adds considerable amount of run time to the adjust phase. This option can be used to reduce this run time. It does not verify that the individual volumes are not used in the functions (TC and COST). If the individual volume sets are used and the option to skip individual volume computation is on (USE_V_ONLY = T), then the value for V1, V2 etc. may-be all zero or some random number. Only use this option if a large number of volume sets are used in highway assignment and check to make sure that individual volume sets are not used in TC and COST functions.
ZONEMSG - |KI| - Optional. Frequency with which the program writes zonal timing messages to the run monitor or console.

Value corresponds to number of zones. For example, with a value of 1, the program writes a message for every zone. With a value of 10, the program writes a message for every 10 zones. With a value of 0, the program writes no zonal messages. Specify a larger value to reduce run times.

Program writes to the run monitor when initiated through Application Editor or voyager.exe. The program writes to the console when initiated through runtpp.exe.

Valid values are greater than or equal to zero. Default value is 1.
ZONES - |KI| - Establishes the number of zones to process. Default value is taken from NETI.

If ZONES is not specified, and the program has no other way to identify the appropriate number of zones, it will be set to 100. Normally, the NETI or MATI matrices will establish the number of zones, but there could be cases where the user wishes to use a different value.
TRACESUMMARY - |K?| - Controls the printed path information from the TRACE PRINTO keyword in PATHLOAD statement. By default, TRACESUMMARY is set to FALSE, in which case the whole path information will be printed to the PRINTO file. If TRACESUMMARY is set to TRUE, only the last link in the IJ path is printed to the PRINTO file along with any other path variables (e.g. _PathCost) listed by the user in the PRINT LIST statement.

Footnotes

These keywords are used to control when to not do any more assignment iterations. In the USA, GAP is a commonly used criteria. Thus, if GAP=0.01, this implies that when the system costs do not change by more than one percent, the process is to terminate. The first of these criteria that is satisfied controls the process. It is suggested that MAXITERS always be used to preclude endless processing. Some networks may never converge, and oscillations may start. Using MAXITERS can prevent useless processing. If MAXITERS ends up being the controlling value, the results printed at the end of the program should be examined to determine if oscillation has occurred, or if more iterations are really needed.

Example

ZONES=3000
COMBINE=WTD, WEIGHTS=1,1,2,3*3,5; 7 iterations
COMBINE=EQUI, MAXITERS=30
PARAMETERS COMBINE=SUM, FRACTIONS=.30,.20,5*.10
      ; 7 Iterations - Incremental
; SAMPLE INCREMENTAL ASSIGNMENT WITH "PROJECTED" RESTRAINT
PARAMETERS COMBINE=SUM, FRACTIONS=.5,.2,.2,.1
ARRAY CSCALE=4
CSCALE[1]=.5, CSCALE[2]=.7, CSCALE[3]=.9, CSCALE[4]=1
PHASE=LINKREAD
   C = LI.CAPACITY * CSCALE[ITERATION]

TRACESUMMARY Example

RUN PGM=HIGHWAY
FILEO PRINTO[1] = "myPath.dat"
FILEI NETI = "C:\Cubetown\Model\HIGHWAY_0001.NET"
FILEI MATI[1] = "{SCENARIO_DIR}\PKHOURTRIPS.MAT"
PARAMETERS TRACESUMMARY = T
PROCESS PHASE=LINKREAD
  C = LI.CAP
ENDPROCESS
PROCESS PHASE=ILOOP
  PATHLOAD PATH=TIME TRACE=(I=1 & J=2) PRINTO=1 LIST= I, J A, B, _PATHCOST
ENDPROCESS
ENDRUN

Output with TRACESUMMARY = F (default)

1	1.00	2.00	1.00	1153.00	0.39
2	1.00	2.00	1153.00	801.00	0.84
3	1.00	2.00	801.00	797.00	1.48
4	1.00	2.00	797.00	955.00	1.60
5	1.00	2.00	955.00	954.00	1.81
6	1.00	2.00	954.00	2.00	2.19

Output with TRACESUMMARY = T

1.00

2.00

954.00

2.00

2.19

Global U-Turn control settings and interaction with Junction file level controls

Global U-turn control settings and interaction with Turn Penalty file level controls

Example A

RUN PGM=HIGHWAY
FILEI TURNPENI = "myTurnPen.pen"
FILEO JUNCTIONO = "myJunOut.INT"
FILEO NETO = "myLoaded.NET"
FILEI JUNCTIONI = "myJunctions.ind",
   period=60,set=1
FILEI NETI = "myBase.net"

PARAMETERS COMBINE = AVE
PARAMETERS RELATIVEGAP=0.0001 GAP = 0.0, MAXITERS=10
PARAMETERS AllowAllUTurns=T ;model U-turns movements at
all nodes unless it is banned in the Junction file

ZONESMSG=1

TURNS N=1-99999

PROCESS PHASE=LINKREAD
   C = LI.CAP
ENDPROCESS

PROCESS PHASE=ILOOP
    MW[1]=500
    PATHLOAD PATH = TIME, VOL[1]=MW[1], PENI=1,2
ENDPROCESS

PROCESS PHASE=ADJUST

FUNCTION {
    V=VOL[1]
   TC = T0 *(1+0.18*(V/C)^8.5)
}
ENDPROCESS

ENDRUN

Example B

RUN PGM=HIGHWAY
FILEI TURNPENI = "myTurnPen.pen"
FILEO JUNCTIONO = "myJunOut.INT"
FILEO NETO = "myLoaded.NET"
FILEI JUNCTIONI = "myJunctions.ind",
   period=60,set=1
FILEI NETI = "myBase.net"

PARAMETERS COMBINE = AVE
PARAMETERS RELATIVEGAP=0.0001 GAP = 0.0, MAXITERS=10
PARAMETERS AllowUTurns=T ;only model U-turns movements where they are
set to ALLOW in the Junction file

ZONESMSG=1
TURNS N=1-99999

PROCESS PHASE=LINKREAD
   C = LI.CAP
ENDPROCESS

PROCESS PHASE=ILOOP
   MW[1]=500
   PATHLOAD PATH = TIME, VOL[1]=MW[1], PENI=1,2
ENDPROCESS

PROCESS PHASE=ADJUST

FUNCTION {
    V=VOL[1]
   TC = T0 *(1+0.18*(V/C)^8.5)
}
ENDPROCESS

ENDRUN

PATHLOAD

Builds a path, generates related matrices, and loads path links.

Keywords and subkeywords include:

CONSOLIDATE
ESTMO
- ALLJ
EXCLUDEGROUP
EXCLUDEJ
FROMNODE
INCLUDEJ
LINKIDARRAY
- LINKIDCNTMW
- LINKIDLASTUSE
- LINKIDMW
- LINKID#MW
MAXPATHCOST
MW[]
- NOACCESS
- SELECTGROUP
- SELECTLINK
- SELECTLINKGROUP
- SELECTTOLL
PATH
- DEC
PATHO
- ALLJ
- FULLPATH
- INCLUDECOST
- NAME
- PATHOGROUP
PENI
PENIFACTOR
SPREADPERC
SPREADPERCVAR
SPREADMAX
SUBAREAMAT
- MAXMSG
TOLLFACTOR
TOLLMATI
- TOLLPATHSET
- THRUNODE
TRACE
TREEO
- NAME
VOL[]
- Valuename

Use a PATHLOAD statement build a path, and then complete other processes based on that path. Selected I-J path traces can be written to the standard output print file, matrices can be generated based upon path criteria, link volumes can be obtained by routing matrix values along the path. Although any of the keywords on the statement can be in any order, the statement is processed in the following specific order:

PATH — Built using any EXCLUDEGROUP and PENI values specified
TRACE
LINKIDARRAY
MW — Processed in the input order
VOL — Loaded in input order

PATHLOAD Keywords

CONSOLIDATE - |?| - Flag that specifies whether to consolidate links that are part of the same road segments prior to path building. Default value is F, no link consolidation.

Consolidating the links reduces the size of the link table and the thus reduces path building time. Depending on the level of inefficiency in the input network, reductions in runtime could be significant. Also see PARAMETERS keyword CONSOLIDATE for information on controlling the effective level of consolidation.
ESTMO - |I| - Integer specifiying which output ICP file, specified by FILEO ESTMICPO, will trap the assigned volumes on screenline links.
ESTMO - ALLJ - |?| - Flag that indicates if ESTMO processing is used for all I-J paths, or for only the I-J paths where an actual assignment is performed. Default value is FALSE.

If the value is TRUE, all potential paths are considered, mostly likely resulting in longer processing times and larger output files.
EXCLUDEGROUP - |IP| - Specifies that links that have any of the designated group codes will be excluded from the path building process.

For example, if HOV links were assigned to group 4, and 4 were one of the excluded values, then none of the paths would contain HOV links.
EXCLUDEJ - |IVP| - Specifies that the processes for the named keywords will exclude the specified destination zones.
FROMNODE - |RS| - Format and report paths from a single origin to a range of destinations, regardless of the current I value. Origin and destination can be any zone or node number but the main purpose of this keyword is to report node to node paths. Zone to zone paths can be reported using just the TRACE keyword without using FROMNODE. Once the FROMNODE keyword is used, none of the other assignment and path related action keywords such as VOL, MW, TREEO, PATHO, ESTMO etc. will be processed. FROMNODE specifies the origin zone or node number. Users can specify FROMNODE as a constant numeric value, or a variable (e.g. FNODE). To specify the destinations of the paths, use the TONODE variable that represent the destination zone/node number in the TRACE expression. For example, TRACE=(TONODE=1-10, 90000-90005 || TONODE=TND). TONODE can be compared to a numeric value, a range (e.g. 1-10) or a variable (e.g. TND). The selected path statistics will be listed in the run print file. Or alternatively, users can use PRINT statement to write path statistics to an external PRINTO file. When using the LIST keyword to output path trace, do not use the variables I and J (when using the FROMNODE keyword), use the variables FROMNODE and TONODE instead.

See FROMNODE example.

Note: An IF (I=1) block is suggested when using the FROMNODE keyword in the ILOOP phase to avoid printing the paths multiple times, one for each I zone.
INCLUDEJ - |IVP| - Specifies that the process for the named keywords will include only the specified destination zones.

Note: INCLUDEJ and EXCLUDEJ should really be mutually exclusive, but they can be combined. When both are used, The INCLUDEJ is processed first, and than the EXCLUDEJ follows. Thus, if INCLUDEJ=100-200 and EXCLUDEJ=140-150, zones 100-139 and 151-200 would be the only destination zones processed.
LINKIDARRAY - |S| - Specifies an array of link attributes; it must be either an LI.array or an LW.array.
LINKIDARRAY - LINKIDCNTMW - |I| - Specifies the MW[] in which to store the number of links in the list.
LINKIDARRAY - LINKIDLASTUSE - |I| - Specifies the MW[] in which to store the information for the last link in the list.
LINKIDARRAY - LINKIDMW - |IP| - List of MW numbers where the monotonic succession of link crossing information (beginning at 1) is to be stored.

For example, LINKIDMW=10-13,6,8 means that the first link’s information will be stored in MW[10]; the second link’s information will be stored in MW[11]; the fifth link’s information will be stored in MW[6], and so on.
LINKIDARRAY - LINKID#MW - |IP| - List of MW numbers where the monotonic succession of numbers of the links (beginning at 1) is to be stored.

For example, LINKID#MW=10-13,6,8 means that the number of the first link will be stored in MW[10]; the second link will be stored in MW[11]; the fifth link will be stored in MW[6]. Link arrays can then be addressed directly by using these values. For example, ANODE=A[MW[1]]xxx=LW.xyz[MW[2]].
MAXPATHCOST - |RS| - Restricts the path builder to build path only to zones/nodes that are less and equal to the value specified by MAXPATHCOST. MAXPATHCOST can only be specified once per PATHLOAD statement. It can be either a numeric constant or an expression. The default value is 0, which means no restrictions.
Note: MAXPATHCOST applies to both path skimming and traffic assignment. When it is used with assignment, trips going to zones beyond the MAXPATHCOST will not be assigned. Therefore, it needs to be used with care

Example.
```
IF (I=1) PATHLOAD PATH=TIME,
VOL[1]=MI.1.1, MAXPATHCOST=I*10+10
PATHLOAD PATH=COST, VOL[1]=MI.1.1,
MAXPATHCOST=50
```
MW[] - |N| - Generates a matrix row, almost in the same manner as a regular COMP MW[]= statement. The primary difference is that this expression has access to the values from the I-J paths that result from the PATH keyword. Two-level indexing is not allowed here; the computation implies a J=1,Zones loop. If there are INCLUDEJ and/or EXCLUDEJ values on the statement, only those corresponding columns in the MW will be processed; the excluded cells will not be altered. There may be multiple MWs specified on the statement; they will be processed in the order they appear on the statement.

Typical types of matrices computed include:
- Path-based matrix - A matrix with I-J path values, such as distance, cost, time, etc. This is often referred to as a LOS (level-of-service) matrix. Many traditionalists refer to such matrices as "skim" values, because the values are skimmed from the network. To obtain zone-zone values, the PATHTRACE(name) function is used. For example, to obtain zone-to- zone times, MW[1]=PATHTRACE(TIME). When the PATHTRACE for the intrazonal value (J=I) cell or a cell with no access is obtained, the value will be a big number, because there is no path between the zones.
  
  In some cases, a big number is acceptable, and in other cases, it is not. To solve this dilemma, you can use the subkeyword NOACCESS to specify a value to be returned from the PATHTRACE function when there is no path.
  
  The keyword PATHCOST may be used to obtain the value directly from the path tables. This is different than PATHTRACE, because PATHTRACE actually traces the path and sums the value from the network links that are in the path. PATHCOST is much faster, because it obtains the values without tracing paths; it also contains any penalty values that were included in building the paths. To provide similar capabilities with PATHTRACE, the argument list to PATHTRACE may include the penalty set numbers that should be added to the values for the first argument to PATHTRACE. Penalty set numbers should be listed individually and cannot be given as a range.
  
  Warning
  
  The program determines when the last iteration has been performed, and no paths or matrices are built from the final network link values. Following the last iteration, MATOs written during normal iteration processing are combined according to the COMBINE option on the MATO statement. Thus, if "skims" had been written in each iteration, and COMBINE=T, the final skim MATO will be the weighted values from all the iterations. This is normally done for trip matrices, but it may be useful for specific travel cost matrices. If COMBINE=F, the MATO will contain the values obtained during the last iteration not after the iteration. To obtain the "true" equilibrium zonal travel time and/or distance, one should run another Highway step using the loaded network as input and skim the shortest path time/distance.
  
  Example of PATHTRACE
```
PATH=TIME,

MW[1]=PATHTRACE(TIME),
   ; zone-to-zones times
MW[2]=PATHTRACE(LI.DISTSNCE),
   ; zone-to-zone distances
MW[3]=PATHTRACE(TIME,2),
   ; same as MW[1], penalties added
MW[4]=PATHCOST
   ; same as MW[3]
```
- Select-link matrix - A matrix of values for the zones that meet select link criteria. There are several different subkeywords that can be used to specify the select-link criteria: SELECTLINK, SELECTGROUP, and SELECTLINKGROUP. Their detailed descriptions are below. All the SELECT… keywords are combined for the MW that they directly follow. Each results in a true or false condition, and if any of them is true, the MW= expression is computed. In the following example, if any of the SELECT criteria is satisfied for a given J, MW[3] for that J will be computed to be the value from MI.1.TRIPS.
  
  Example of Select Link
```
PATH=COST,
MW[3]=MI.1.TRIPS,
SELECTLINK=(L=1000-1001 && L=2000- 2001),
SELECTGROUP=1-3,5,
SELECTLINKGROUP=((GRP[1]=1 && GRP[2]=2) || (GRP[3]=1))
```
MW[] - NOACCESS - |R| - Specifies a number to be returned from the PATHTRACE function when there is no path from the current I to the destination (J) zone. Default value is 1,000,000.
MW[] - SELECTGROUP - |IPa| - Specifies the group codes for selection. A path has to include at least one link that has any of the specified group codes. If the selection is 1-3, 7, then at least one link in the path has to have a group code of either 1, 2, 3, or 7.
MW[] - SELECTLINK - |s| - Expression used to determine if the I-J path uses certain facilities. The expression must be enclosed within parenthesis, and can contain any of the following variables:
- A - The A-node of a link; only useful to select links with a path begins at A.
- B - The B-node of a link; only useful to select links with a path ends at B.
- N - A node that must be used in the path.
- L - A link that must be used in the path. Links are coded as A-B (directional) or A-B* (non-directional – link may be traversed in either direction).
Any of these variables can have multiple values specified for them. Nodes (A, B, N) can be specified as single values and/or as ranges; L can have multiple links specified. When the multiple value specification is used, the implication is a logical OR amongst the values. Example: N=100,105,200-205 means if N is 100, or if N is 105, or if N is a value between 200 and 205, inclusive. There is no limitation on the number of nodes.

The selection is processed by examining each link/node in the path, on both an individual link and a total path basis. The process is from left to right. Each link/node is processed, and as long as it does not fail any conditions, it is considered as a candidate for processing in the total path. In the total path basis, the link/node is considered in conjunction with other links/nodes in the path. Examples may better illustrate the process.

Sample path: 1-101-102-103-104-105-2

(A=1) Node 1 is on the path in any link except the last: true

(A=1 && B=102) Node 1 is on the path in any link except the last, and node 102 is on the path in any link but the first: true

(L=101-102,104-200) Link 101-102, or Link 104-200 is on the path: true

(L=102-101*) The path contains link 101-102 or link 102- 101: true

(L=101-102* && L=104-105*) The path contains link (101- 102 or 102-101) and link (104-105 or 105-104): true

(N=101 && N=105-110 && L=101-102*) The path contains node 101 and any node in the range of 105-110, and link (101-102 or 102-101): true

((N=100-105) && (N=8,57 || L=105-104)) The path crosses any node 100-105, and (it crosses node (8 or 57) or link 105-104): false. If L=104-105* instead of L=104-105, the expression would be true.

Bentley recommends using nested parentheses to help categorize the comparison sets. With this type of Boolean selection, most any desired combination of path usage can be specified.

Finally, when using SELECTLINK and the TURNS control statement in the same HIGHWAY program, care must be taken. Please see TURNS for more information.
MW[] - SELECTLINKGROUP - |s| - Expression used to determine if the I-J path meets select link criteria based upon some level of link group codes. The expression should contain mostly GRP[] values and perhaps I and J; nothing else is really appropriate. The tracing mechanism accumulates how many links of each group code are used in the path. Those totals are available to the expression. The following example says "if the path uses at least three links with group code 1 and at least one link with group 2 or if the path uses at least five links with group 7 or if the path uses exactly two group 6 links" the path meets SELECTLINKGROUP criteria.

Example
```
SELECTLINKGROUP=((grp[1]>3 &&
grp[2]>=1)|| grp[7]>=5 || grp[6]=2)
```
MW[] - SELECTTOLL - |s| - Expression used to determine if the I-J path uses certain toll facilities. The expression must be enclosed within parenthesis, and can contain any of the following variables:
- T - The toll trip entry-exit pair specified using toll gate numbers. E.g. T=1-4 means any trips using entry gate 1 and exit gate 4.
- G - A toll gate (entry or exit) that must be used in the path.
- E - An entry gate that must be used in the path.
- X - An exit gate that must be used in the path.
Any of these variables can have multiple values specified for them. Gates (G, E, X) can be specified as single values and/or as ranges; T can have multiple entry-exit pairs specified. When the multiple value specification is used, the implication is a logical OR amongst the values. Example: G=100,105,200-205 means if G is 100, or if G is 105, or if G is a value between 200 and 205, inclusive.

Example 11: Using TOLLMATI and TOLLVOLO

Example:
```
PATHLOAD PATH=TIME VOL[1]=MW[1] VOL[2]=mw[2] TOLLMATI=1,1,
           mw[101]=mw[1] SELECTTOLL=(T=10-110),
           MW[102]=MW[1] SELECTTOLL=(E=1-10 && X=101-110),
           MW[103]=MW[2] SELECTTOLL=(G=15)

PATHLOAD PATH=TIME VOL[3]=MW[3] TOLLMATI=1,2,
           MW[301]=MW[3] SELECTTOLL=(T=1-101 || (E=21-30 && X=121-130))
```
PATH - |KS| - Specifies the link value on which the paths are to be built. Valid values are: Cost, Time, Dist, LI.name, or LW.name.
PATH - DEC - |S| - Specifies the accuracy of the link value on which the paths are to be built. Default value is F. Valid values for DECare:0,1,2,3,4,FandF2whichrepresent0,1,2,3,4 decimal places, floating point and optimized floating point, respectively. Using lower accuracy will speed up the assignment process considerably, especially for larger networks. Using DEC=F2 (optimized floating point) will provide the same accuracy as DEC=F with improved run time performance.
PATHO - |I| - Number (#) to specify that a path file is to be written to FILEO PATHO[#]. The file will contain I-J paths generated by this PATHLOAD statement. The number of I-J paths will be determined by the value of the PATHLOADPATHO ALLJ keyword. If PATHO is not specified, the PATHO file will not be written for this statement. The path file can be used in CUBE for analysis of what happened during this assignment, or for various post processing capabilities, such as selected link analysis, or recreation of parts of the assignment. The generated file can be very large and writing it can cause a considerable increase in running time.
PATHO - ALLJ - |?| - Switch that indicates if PATHO write processing is to be invoked for all I-J paths, or for only the I-J paths where an actual assignment is performed. By default this value is false, unless this application is path building only (No FILEO NETO=value and no PATHLOAD VOL=value).
PATHO - FULLPATH - |?| - T/F flag used with PATHOGROUP to keep partial or full paths for the specified GROUP(s).
PATHO - INCLUDECOST - |?| - Switch to indicate if the path records are to include the cost values (based upon the PATH=array values). The cost through every link in every path is written; this can cause a considerable increase in the size of the file.
PATHO - NAME - |S| - Name to be applied to the paths written for this statement. A PATHO file may have multiple path sets written to it by different PATHLOAD statements. However, the same NAME path set may not be written to a file more than one time for an I zone. If an attempt to write the same NAME to a file for the same I zone is made, only the first set will be written, and there will be no message indicating that this attempted duplication occurred.
PATHO - PATHOGROUP - |IP| - List of numbers (1-32). The numbers are associated with GROUP ADDTOGROUP= process in LINKREAD. The ADDTOGROUP numbers are typically associated with specific LI. or LW. values via a conditional statement thus links are either associated with the group or not. When the trace of a path is examined, if the trace does not contain any of the selected links in the group(s) nothing is written to the PATHO file. If the path does contain a specified link in the group(s), and the FULLPATH subkeyword is F, the trace will contain only I, the nodes of the specified links in the group(s), and J. If the path does contain a specified link in the group(s), and the FULLPATH subkeyword is T, the trace will contain I, all the nodes of any path that uses any of the specified links in the group(s), and J.

The use of PATHOGROUP= with FULLPATH=T/F and setting appropriate group(s) with ADDTOGROUP= allows the user to limit the paths written to the PATHO file by keeping only those paths and the portions of the paths the user may be interested in for further analysis and display. This can considerable reduce the size of the stored path file.
PENI - |IP| - Specifies the PENI set(s) that are to be used in building this path. You can specify any combination of valid PENI indices. A set number must be 1-8; the valid numbers on the TURNPENI file. If a JUNCTIONI file is provided, then the SET keyword is required to reserve one penalty set numbers for use with the junction delays. The set number used for the junction delays must be listed on the PENI keyword value along with any additional turn penalty set that may be specified with TURNPENI in the same run.
PENIFACTOR - |N| - Expression that specifies a factor for all penalties during path building. This is not specifically related to JUNCTION; it applies to all penalties (TURNPENI and SET=).
SPREADPERC - |R| - Stochastic Assignment – used with COMBINE=PROBIT|BURRELL, and in conjunction with SPREADPERCVAR and SPREADPERCMAX.

SPREADPERC specifies the percent spread used to calculate the spread range value, it must be a numeric constant. Default is 10(%).

A random link cost value (for PATH=x) will be selected from the +/- spread range value from the original link cost value (C) as follows:
```
Min(SPREADPERC/100 * sqrt(C), C, SPREADMAX)
```
SPREADPERCVAR - |S| - Single variable or link array (must be LI. Or LW.) which indicates the percent spread for a link during stochastic assignment. If it is a link array, then every link can have a different spread percentage. If the value for a link is negative, then the SPREADPERC value will be used.
SPREADMAX - |R| - Specifies the maximum spread value allowed for stochastic assignment (COMBINE=PROBIT|BURRELL). Default is unlimited.
SUBAREAMAT - |N| - Expression that the program computes for every J and writes the resulting value onto any subarea extracted records.

For example: SUBAREAMAT[1]=MW[3] specifies that for every J of the current I path set, if the path from I-J has some portion within the subarea, a value is to be inserted to the subarea matrix.

There must be an index for the keyword. The highest index sets the number of matrices on the SUBAREAMAT file. See ILOOP phase.
SUBAREAMAT - MAXMSG - |I2| - Specifies how many messages to print about improper cordon crossings and the error level to assign to the messages.

Two values are allowed:
- The first value specifies how many messages are printed for the SUBAREAMAT.
- The second value specifies the error level to assign to the message when the number of messages reaches the first value.
The printed messages will be assigned an error level of 1 less than the second value for all messages except the last one.

For example: MAXMSG=50,2 indicates that the first 50 improper crossings are to be printed at error level 1, but the program will terminate with error level 2, at the 50th message.
TOLLFACTOR - |N| - Expression that specifies a factor for converting tolls to COST units. Generally paths are built on TIME and TIME is in the units of minutes. If a generalized COST function is used for path building, all components of this function are typically appropriately factored to be in generalized minutes.

Units must be (path cost units)/(toll cost units). For example, if tolls are coded in $US and path costs in minutes, then the TOLLFACTOR expression must specify a value in minutes/$US. An assumed traveler value of time of US$15/Hour would be implemented by setting TOLLFACTOR to 4 (60/VOT).
TOLLMATI - |IP| - Indicates that gate-to-gate tolls are to be included in the COST used for path building and specifies the FILEI TOLLMATI[#]= file number and toll set on the file to be used. Specifying TOLLMATI=1,2 indicates to use toll set 2 on TOLLMATI file 1.

See Path-based tolls.
TOLLMATI - TOLLPATHSET - |I| - This keyword, when specified, triggers the saving of the toll trips for output to the TOLLVOLO files at the end of the process. It is also the identifier to the toll trips saved from this PATHLOAD. The value can be between 1 and 1000. Along with toll matrix and toll set number specified in the TOLLMATI keyword, the VOL sets specified in the PATHLOAD statement, these four constitute the unique identifiers for a specific group of toll trips (TOLLMATI, TOLLSET, PATHSET and VOLSET). Toll trips with the same 4 identifiers will be summed together into a group.

Example 11: Using TOLLMATI and TOLLVOLO.

TOLLMATI Example
```
PATHLOAD PATH=TIME VOL[1]=MW[1] VOL[2]2=mw[2] TOLLMATI=1,1 TOLLPATHSET=1 EXCLUDEGROUP=1
PATHLOAD PATH=TIME VOL[3]=MW[3] TOLLMATI=1,2 TOLLPATHSET=2
```
In the above simple PATHLOAD statements, there are three unique set of toll trips
1. TOLLMATRIX=1, TOLLSET=1, PATHSET=1, VOL=1
2. TOLLMATRIX=1, TOLLSET=1, PATHSET=1, VOL=2
3. TOLLMATRIX=1, TOLLSET=2, PATHSET=2, VOL=3
THRUNODE - |I| - Sets the minimum node number allowed to be included in the path building process. The value has to be a positive integer. The default value is ZONES+1. The default value excludes centroids as intermediate points of a path.
TRACE - |S| - Specifies if any paths from I/FROMNODE to the selected destinations are to be formatted and reported for this path. The select expression must be enclosed within parenthesis. Most likely, the variables used in the expression would be I, J, TONODE and Iteration, but any valid variable can be used. The TRACE expression is evaluated for J=1,Zones when FROMNODE is not specified and TONODE=1 to HighestNodeNumber when FROMNODE is specified. If PARAMETERTRACESUMMARY is set to true, only the last link in the path is printed to the PRINTO file along with any other path variables (e.g. _PathCost) listed by the user in the PRINT LIST statement.

Example:
```
PATHLOAD PATH=TIME TRACE=(I=1-10 & J=100- 150)
PATHLOAD PATH=TIME FROMNODE=10000
TRACE=(TONODE=100-150)
PATHLOAD PATH=TIME FROMNODE=100
TRACE=(TONODE=11000-11500)
PATHLOAD PATH=TIME FROMNODE=10000
TRACE=(TONODE=1-100 || TONODE=11000- 11500)
```
The selected path traces will be listed in the run print file.

The TRACE keyword can use the PRINT statement keywords as subkeywords to format and direct the print of the path trace(s) to an external PRINTO file. The following additional subkeywords can be used:

PRINTO (REWIND PRINT) CSV CFORM FORM LIST

See PRINT for details on these subkeywords.

The LIST subkeyword may be any valid input (li.) or work (lw.) array or it can be set to _pathcost to list the accumulated value of the COST function along the path trace.

See TRACE example.
TREEO - |I| - Index of the output TREEO file, to which the path trees from the PATHLOAD should be output.

See more information on TREEO from Example 10: Shortest Path Trees Using TREEO.
TREEO - NAME - |S| - Name for this path set, which will be output to the TREEO file.
VOL[] - |N| - Specifies an expression to be solved for J, and that the result of the expression is to be assigned to the links in the path generated by the PATH keyword. VOL should be indexed [], but if it is not, the index is implied to be 1. The index range is 1-1000; there may be up to 1000 volume sets in a single application of Highway. The values are added to the volumes. In most cases, there will be a single VOL for a PATHLOAD statement, but there are many cases, where it will be advantageous to have more than one VOL. For example, if a standard assignment is to be performed, and it is desired to have another assignment made of just the trips that meet select link criteria, that is easily accomplished. Or, perhaps it is desired to assign all vehicles, and to determine what types of trips make up the volumes on each link. The examples below illustrate these capabilities. It should be noted that when specifying multiple VOL keywords, you must specify the FUNCTION V so the program knows which VOL combinations are to be used for capacity analysis.
VOL[] - Valuename - |S| - Specifies the name of a link value that should be used in restricting the links that should be included in the VOL assignment. The primary use of this keyword is for air quality analysis. An example would be to obtain what portion of the volume on a link is in cold start mode. In that case, VOL[2]=MI.1.TRIPS,TIME=0-7.5 would mean to assign only to the links that are within 7.5 minutes from the origin zone. A single range of numbers is required for this keyword. In the example, if a 3 minute link’s A node were 6 minutes from I, only 50% of the trip value would be added to the link volume (7.5 is 50% of the way from 6 minutes to 9 minutes). Normally, the range would be 0-some number, but if the range were say, 7.5-99999, only the hot running portion of the trip would be assigned.

Trace Example

RUN PGM=HIGHWAY
FILEO PRINTO[1] = PATH.CSV
FILEO PRINTO[2] = PATH_TRACE_RPT.DAT FILEI NETI = TEST.NET
FromZone=150
ToZone=187
PHASE = LINKREAD lw.fac_dist=10*li.DISTANCE ENDPHASE
PROCESS PHASE=ILOOP
IF (I=FromZone) ; build paths for select I
PATHLOAD PATH=li.TIME mw[1]=PATHTRACE(li.TIME),
mw[2]=PATHTRACE(li.DISTANCE), TRACE=(I=FromZone & J=ToZone)
PRINTO=2 PRINT=T
F=6.0,LIST=I,J,A,B,li.TIME(8.3),_pathcost(8.3),
li.DISTANCE(8.4),lw.fac_dist(10.2)
EXIT
ENDIF
ENDPROCESS
ENDRUN

FROMNODE example

RUN PGM=HIGHWAY
FILEI NETI = "Highway.NET"
FILEO PRINTO[1] = PATH_TIME_DISTANCE.PRN FILEO PRINTO[2] = PATH_100500.PRN
FILEO PRINTO[3] = PATH_101000_TIME.PRN

LOOKUP NAME=FROM_TO,
      LOOKUP[1]=1, RESULT=2, ; lookup from node
      LOOKUP[2]=1, RESULT=3, ; lookup to node
      R= '1 106500 76011',
               '2  106722  83000',
               '3  107100  92650',
               '4  107122  100000',
               '5  103500  101000'
PROCESS PHASE=ILOOP
  IF (I=1)
    LOOP _N=1,5
      FND=FROM_TO(1,_N)
      TND=FROM_TO(2,_N)

      PATHLOAD PATH=LI.TIME FROMNODE=FND, TRACE=(TONODE=TND)

      PATHLOAD PATH=LI.TIME FROMNODE=FND, TRACE=(TONODE = 75180-75190 || TONODE>=107170) PRINTO=1, LIST=FROMNODE,TONODE,A,B,LI.TIME(10.2),LI.DISTANCE(10.2)

      PATHLOAD PATH=LI.TIME FROMNODE=100500, TRACE=(TONODE=TND) PRINTO=2 LIST=FROMNODE,TONODE,A,B,LI.TIME(10.2)
     ENDLOOP

      PATHLOAD PATH=LI.TIME FROMNODE=101000, TRACE=(TONODE=76000,100000-100100) PRINTO=3 LIST=FROMNODE,TONODE,A,B,LI.TIME(10.2)
  ENDIFENDPROCESS
ENDRUN

Example: using TRACESUMMARY to print path cost from origin node to destination node

RUN PGM=HIGHWAY
FILEI NETI = "Highway.NET"
FILEO PRINTO[1]="PATHCOST.PRN"

PARAMETERS TRACESUMMARY=T

PHASE=ILOOP
IF (I=1)
   PATHLOAD PATH=LW.TIME FROMNODE=100500,
TRACE=(TONODE=76000,100000-100100) PRINTO=1
LIST=FROMNODE,TONODE,_pathcost(10.2)
ENDIF
ENDPHASE
ENDRUN

An example of getting toll costs would entail having a LOOKUP function where the lookup value is the gate-gate combination traversed on the path and the result of the function is the toll value associated with gate-gate movement.

LINKIDMW=1-2
Cost = tolllook(MW[1]*1000+MW[2])

See Example 6: Toll Gate accumulation using LINKIDARRAY on page 315 for an example of using the LINKIDARRAY keyword and its subkeywords in a script.

PATHLOAD example

PATHLOAD PATH=COST, VOL[1]=MI.1.ODTRIPS
PATHLOAD PATH=COST, MW[6]=MW[3], SELECTLINK=(L=2001-2004),
VOL[1]=MW[3], VOL[2]=MW[6],VOL[3]=MW[3],TIME=0-7.5

This first PATHLOAD statement causes the COST paths to be built, and then the values from MI.1.ODTRIPS are assigned and added to VOL[1].

The second PATHLOAD statement causes the following sequence of events:

COST paths are built.
MW[6] is set equal to the values in MW[3] for the Js whose path from I crosses link 2001-2004. Note that MW[6] was cleared at the beginning of the ILOOP for I, but if the user caused any values to be set into MW[6] prior to this statement, the MW[6] values could be incorrect.
The values from MW[3] are assigned to the COST paths and added into VOL[1] volumes.
The values from MW[6] (the selected link trips) are assigned to the COST paths and added into VOL[2].
The values from MW[3] are assigned to only the links that are within 7.5 minutes from I and added into VOL[3] (these are the cold start volumes).

Example

/*
The first PATHLOAD statement below (PATH is a trigger keyword – PATHLOAD is not required) builds the DISTANCE paths and illustrates two different ways to extract a LOS matrix for the path.
The second PATHLOAD statement builds the COST path using penalties and shows that the two extracted matrices are not necessarily the same because of the penalties. The comments illustrate how to properly skim a path when penalties should be incorporated.
*/
PATH=LI.DISTANCE,MW[1]=PATHTRACE(LI.DISTANCE),MW[2]=PATHCOST
; MW[1] and MW[2] are the same in this case
PATH=TIME, PENI=1,3 MW[1]=PATHTRACE(COST),MW[2]=PATHCOST
; MW[1]and MW[2] could be different because penalties are used
; in the path. If MW[1]=PATHTRACE(TIME,1,3),they would be the same.
/*
Following is an example of trip splitting based upon the relative difference of time if a link (say, a bridge) is added to the network. In this example the link is already in the network, and it can be unavailable to the path builder by excluding links with group code 1. The steps are: 1. Compute the time path with the bridge included and extract the times along the path into MW[1].
2. Compute another path with the bridge excluded (group=1)and extract the times along the path into MW[2]
3. Compute a path split based upon the total times for the two sets of paths. The portion of trips that would use the bridge path is computed based upon the values in the two time LOS matrices [1] and [2]. If the time saved exceeds 10 minutes and the relative saving (time saved / total trip time) is greater than 15 percent, the portion of trips that will use the bridge path is set equal to the relative saving. (This is to illustrate a method of application, and is not meant to imply any type of realistic diversion.)
4. Assign a portion of the trips to the one path set, and the remaining trips to the other path set. The two assignments are made to the same volume set, but, they could have just as easily be kept separate.
*/
PHASE=LINKREAD
If ((A=1001 & B=1002) | (A=1002 & B=1001)) ADDTOGROUP=1
PHASE=ILOOP
PATHLOAD PATH=TIME, MW[1]=PATHTRACE(TIME) ;w bridge
PATHLOAD PATH=TIME, EXCLUDEGROUP=1 MW[2]=PATHTRACE(TIME) ;wo bridge
JLOOP; MW[3] = the fraction of trips diverted to the bridge path
TimeSaved = MW[2] - MW[1]; 2 is always >= 1.
Divert = 0
RelativeSaving = TimeSaved / MW[2]
IF (TimeSaved > 10 && RelativeSaving >.15)Divert = RelativeSaving
MW[3] = Divert
ENDJLOOP
;assign bridge trips
PATHLOAD PATH=TIME, VOL[1]=MI.1.TRIPS*MW[3]
PATHLOAD PATH=TIME, EXCLUDEGROUP=1, VOL[1]=MI.1.TRIPS*(1-MW[3])

Formats and prints a line of information. See PRINT for details.

Example

IF (ITERATION = 0) ; LIST INPUT LINKS
LIST= A(5), B(5), NI.DIST(6), T0(6.2)
ENDIF
IF (ADJUST=1 && ITERATION >5 && VC >2.0) LIST='BIGVC for: ',A,B,VC(5.2)

PRINTROW

Formats and prints row(s) of matrices. See PRINTROW for details.

Example

PRINTROW mw=1-2,1 form=LRD title='form=LRD'
PRINTROW mw=1-21 form=6D base1=y maxperline=10 form=6D,
base1=y maxperline=10

PROCESS

Establishes phase blocks. Keywords include:

A user process phase stack is defined by a PROCESS statement that names it and an ENDPROCESS statement that ends it. To simplify coding, the PROCESS control word is not necessary; PHASE=name may be used directly. And, to further simplify coding, the ENDPROCESS statement is not necessary; the occurrence of another PROCESS statement acts as the ENDPROCESS statement. If ENDPROCESS is used, it may be coded as either ENDPROCESS or ENDPHASE.

PROCESS keywords

PHASE - |KS| - Names the phase stack. The control statements that follow it, until an ENDPROCESS statement or another PROCESS statement is encountered, will be executed when the phase is internally executed.

Exception: Static statements, such as PARAMETERS, FILEI, FILEO, and LOOKUP, are not processed within the stack, even if that is where they are coded.

The following names may be specified:
- SETUP
- LINKREAD
- ILOOP
- ADJUST
ENDPHASE - |K| - Defines the end of the user control statements for a stack.

Example

PHASE=LINKREAD
   T0 = LI.DISTANCE*60 / SPEED
ENDPHASE
PHASE=ILOOP
   PATH=TIME, VOL[1]=MI.1.ODTRIPS
ENDPHASE
PHASE=ADJUST
   LW.TIME = TIME * LW.FLAGCODE
ENDPHASE

REPORT

Requests reports and establishes tracing. Keywords and sub-keywords include:

REPORT keywords

CAPACITY - |?| - Switch that indicates if the capacity portion on the SPDCAP tables is to be reported.
PENI - |?| - Switch to turn off dynamic printing of the turn delays calculated by the junction model and reported every iteration. If there are a larger number of junctions coded in the network then PENI=T could result in voluminous print file.
SPEED - |?| - Switch that indicates if the speed portion on the SPDCAP tables is to be reported.
TRACE - |K?| - Controls the listing of the stack statements as they are processed (can be quite voluminous, so be careful). Trace can be turned on and off at any time, thus controlling the amount of output as desired. If a COMP is traced, only the first five J values will be reported.
VDTSPD - |?| - Switch that indicates if the vehicle distance traveled stratified by average trip speed is reported. Note that this report requires considerably more computer resources (both process time and disk space). If no subkeywords are appended to this keyword, the program will simulate: RANGE=0- 100-1. There may be any number of VDTSPD keywords.
VDTSPD - I - |IV| - Specifies which origin zones are to be included in this report. If this keyword is not specified, all origin zones will be included.
VDTSPD - J - |IV| - Specifies which destination zones are to be included in this report. If this keyword is not specified, all destination zones will be included.
VDTSPD - FILE - |F| - Specifies a file where the VDTSPD reports are to be written (exported) in a format that can be easily read by most spreadsheet software. Specifying** FILE** will not preclude the reports from being printed. If the same file is specified following different VDTSPD keywords, the output will be stacked onto the file.
VDTSPD - RANGE - |IP| - Specifies the speed stratification for this report. The values can have at most one decimal place. There must be at least two values, and possibly three for each sub report. For example:
- RANGE=0-100 specifies that the report is to have only one number reported.
- RANGE=0-100-1 specifies that the report is to have 100 values reported.
- RANGE=0-7.5,7.5-100-5specifies that two different schemes are to be obtained.
With multiple RANGE sets, an I-J value can be placed into more than one RANGE set. Each subreport will not only contain values for the RANGE specified, it will also include any values less than the low value and any values greater than the highest value.

If RANGE=2-5-1 is specified, the printed report will appear as:
- x - 2 — Interval includes speeds >= x and < 2, x is the lowest speed found
- 2 - 3 — Interval includes speeds >= 2 and < 3
- 3 - 4 — Interval includes speeds >= 3 and < 4
- 4 - 5 — Interval includes speeds >= 4 and < 5
- 5 - y — Interval includes speeds >= 5, y is the highest speed found
VDTSPD - VOL - |IP| - Specifies which volume sets are to be included in this report. If this keyword is not specified, the program will report all volume sets.
ZDAT - |?| - Switch that indicates if all the internal arrays obtained from FILEI ZDATI files are to be reported.
ZDAT - DEC - |I| - Sets the maximum number of decimal places to be printed for any variable. This one value applies to all variables on all ZDATI statements.

Example

TRACE=y ; turn stack tracing on
REPORT CAPACITY=yes
         ; report the capacities by lane by CAPCLASS
REPORT VDTSPD=T,
VOL=1, I=1-933, J=1-933,
RANGES=0-7.5, 7.5-100-5,
FILE=VDTSPD.TXT

SET

Sets multiple variables or arrays to the same value. .. cssclass:: keywords-list

VAL
VARS

Use SET to set any number of variables to some value. All variables are set to zero when they are first allocated. COMP statements produce most changes. A COMP statement is not as efficient as a SET statement.

SET keywords

VAL - |R| - Value that the VARS that follow will be set to. It must be a numeric constant. VAL is initialized to zero when the statement is encountered.
VARS - |S| - List of variables that are to be set to the more recent value of VAL obtained from this statement. If a VARS is the name of an array established on an ARRAY statement, the entire array will be set to VAL.

Example

SET VAL=0, VARS=TOT1,TOT2,COUNTER
 TOT1=0 TOT2=0 COUNTER=0
              ; is a COMP statement to do the same thing
 SET VARS=TOT1 TOT2 COUNTER ; is also the same (VAL is 0)
 SET VAL=123 VARS=C123, VARS=TOT1, TOT2, TOT3
              ; sets all to 123
 SET VAL=0, VARS=VA1,VA2,VA3, VAL=100, VARS=VX, VY

SETGROUP

Sets group codes for a link.

Use SETGROUP to set group codes for a link; it is applicable during only the LINKREAD phase. Group codes are used primarily for designating links that are to be excluded in path-building, and for inclusion in select link analysis. Each link can have up to 32 different group codes assigned to it. The codes are numbered 1-32. There are no preconceived definitions for the codes; that is the user’s responsibility. Group codes can be quite helpful in project analysis or for determining specific interchange to interchange movements.

SETGROUP keywords

ADDTOGROUP - |KIP| - Specifies that the current link is to be assigned the codes that are in the value list.
REMOVEFROMGROUP - |KIP| - Specifies that the current link is to have the designated values removed from its codes. This keyword normally should not be used.

Example

PHASE=LINKREAD
   IF (LI.SPDCLASS==1-3,6,9,55) ADDTOGROUP=1

SORT

Sorts user-defined arrays. See SORT for details.

SPDCAP

Revises speed and capacity tables.

The SPDCAP statement is the same as that used in the Network program to revise the SPEED and CAPACITY tables attached to the network. If this statement is used in the control file for the Highway program, the values from the NETI are updated when NETI is opened. This capability allows you to test various scenarios without having to modify the network. The revised tables will be written to the NETO file.

SPDCAP keywords

CAPACITY - |RV*99| - Capacity in vehicles per lane per hour. Actual link capacity is obtained by multiplying the link capacity based upon its capacity classification (CAPCLASS) value by the number of LANES. All values must be 0- 9999, inclusive. The capacity array is initialized to 20 times the index number, for all lane stratification (CAPACITY[1]=20, CAPACITY[2]=40…).
LANES - |IV| - Lane stratification that any following CAPACITY and/or SPEED values are to apply to. LANES may be interspersed with other keywords and values on the statement. All values must be 1-9, inclusive.
SPEED - |RV*99| - Speed to be applied to the link. All values must be 0- 3276.7, inclusive. The speed array is initialized to the index number, for all lane stratification (SPEED[1…99]=1,2,…99). Speed is maintained with one decimal place.

A network contains an array of capacity and speed data. Each array is dimensioned with ninety-nine values for each of nine lane stratification, and contains 891 values. When an array is accessed, the program uses the number of lanes (LANES) as the row index, and the capacity and/or speed classification (CAPCLASS, SPDCLASS) as the column index to obtain a value for a link. If** CAPACITY** or SPEED is encountered prior to a LANES keyword on the statement, LANES will be preset to 1-9. CAPACITY and SPEED are entered as vector data, and may be indexed to set a specific loading place, and may have null fields to skip the revision of certain columns. The SPEEDFOR and CAPACITYFOR functions can be used to obtain values for these tables.

Example

;Set entire table to 50,
; then revise the values for 20,21, and 24 for lanes 1,3,8

SPDCAP CAPACITY=99*50, LANES=1,3,8, CAPACITY[20]=300,400,,,700
SPDCAP LANES=2,4-9, SPEED=20.5,30.3,50.6,,,88.2, LANES=5,SPEED[15]=15
SPDCAP SPEED=30, LANES=2-8; Inappropriate; the LANES will not be used.

TURNS

Requests turning movement volumes.

Use TURNS to request that the volumes at specific interchanges (nodes) be accumulated. If there is at least one TURNS statement, the program will accumulate turns for every PATHLOAD VOL[]= statement that is present. At the end of each iteration (in the Adjust phase), a single total turn volume will be computed for each movement at the nodes where turns are requested (these volumes may also be used by an intersection model, if one exists).

By default, the single volume is computed by adding all the individual turn volume sets together (T = TURN[1] + TURN [2] + TURN [..] …). This default accumulation process can be overridden by using the T= capabilities on this statement. Usually, the T= expression should be parallel to the V= expression that is specified on a FUNCTION statement. If additional volume sets are required for SELECTLINK analysis, only the turn volume sets corresponding to the original volume indices should be summed. This avoids double counting in the TURNS request.

For example, when

FUNCTION V = VOL[1] + VOL[2]

Then the corresponding TURNS request should be:

TURNS T = TURN[1] + TURN[2]

The value of T for each movement will be computed in the Adjust phase, and then combined with other iteration values to form the "combined" volume.

By default, when there is no ‘N=XXX-XXX’ set specified by the user (or no TURNS statement), the Highway program will only consider junction related nodes and links (from the input junctions file) in the turn volume accumulation and corresponding iteration-by- iteration statistics’ calculation. Users should decide to set N=XXX- XXX accordingly to their requirements in terms of turn volumes accumulation and corresponding statistics calculation (e.g., when using TURNPENI, to accumulate non-junction nodes).

To accumulate turn volumes, you must specify a FILEO TURNVOLO statement. The turn volumes will be written to the file(s) specified on that statement.

TURNS keywords

N - |IP| - List of nodes at which turning volumes are to be accumulated. Default: only junction related nodes.
T - |N| - Expression used to compute the total volume at each of the nodes.

EXAMPLE

FILEO TURNVOLO=myfile.trn, FORMAT=BIN
qTURNS N=1000-2000,3000,5000-6000,19000-32000, T=TURN[1] + TURN[3]